diff --git a/readme.md b/readme.md index 8f894e3..0e619b0 100644 --- a/readme.md +++ b/readme.md @@ -8,11 +8,11 @@ This package has been published with a number of dist-tags meant for different p - `stable`: Production environment - `beta`: Sandbox environment -- `canary`: For developers to test on core components +- `canary`: For developers to test on core components ## Usage as a block dependency: -Include as an dependency in a custom block: +Include as an dependency in a custom block: `blocks/card-list-block/package.json` @@ -51,17 +51,17 @@ Include as an dependency in a custom block: ``` -## Linking and Debugging +## Linking and Debugging - Specify the cssFramework on `blocks.json` of feature pack - and run `npx fusion start` with `useLocal` set to `true` in `blocks.json` -## Contributing +## Contributing ### Local Development Commands: -- `npm i` Install dependencies for library -- `npm run build-all` Create output for style guide +- `npm i` Install dependencies for library +- `npm run build-all` Create output for style guide ### Publish The Style Guide @@ -77,14 +77,14 @@ Include as an dependency in a custom block: The [styleguide](https://staging.arcpublishing.com/alc/docs/styleguides/news-theme-css) is generated using a modified version of [michelangelo](https://github.com/stamkracht/michelangelo) in the `/michelangelo` folder. - Go to michelangelo/kss_styleguide/custom-template/index.hbs -- Change relevant issues +- Change relevant issues - Make sure to run `npm run build-all` to see effect - View locally in styleguide/index.html ### To publish a new beta version -1. Check `staging` version in `package.json` under version. As a sanity check, you can also look at published version to GitHub packages via `npm view @wpmedia/news-theme-css time`. This will show what versions have been published. -2. Look at how `news-theme-css` is used by themes blocks. Check for the latest `@beta` version via `npm view @wpmedia/news-theme-css@beta`. -3. Update the version `npm version prerelease --preid=beta`. +1. Check `staging` version in `package.json` under version. As a sanity check, you can also look at published version to GitHub packages via `npm view @wpmedia/news-theme-css time`. This will show what versions have been published. +2. Look at how `news-theme-css` is used by themes blocks. Check for the latest `@beta` version via `npm view @wpmedia/news-theme-css@beta`. +3. Update the version `npm version prerelease --preid=beta`. 4. Publish to the beta dist-tag `npm publish --tag beta` block/package.json @@ -98,7 +98,7 @@ block/package.json 3. Push the version update to `staging`. 4. Publish the beta-tagged version `npm publish --tag beta` -### To test a beta or canary version +### To test a beta or canary version - For canary, do the same steps as above but with canary instead of beta - Fusion will then inject these overrides and framework. Set the following in the feature pack's blocks.json: @@ -111,7 +111,7 @@ block/package.json ``` -Include as an dependency in a custom block: +Include as an dependency in a custom block: `blocks/card-list-block/package.json` diff --git a/scss/homepage.md b/scss/homepage.md index eeecf28..56486bd 100644 --- a/scss/homepage.md +++ b/scss/homepage.md @@ -6,11 +6,17 @@ This is the CSS framework for the Fusion News Theme that provides the foundation - Typography - Breakpoints and spacing - Utility Sass functions (i.e. convert px to rems, etc.) -- A JavaScript package that has versions of some of the Sass functions (i.e. `calculateRem`, `lightenDarkenColor` ) as well as an object -(`framework`) that holds properties for spacing, breakpoints, etc. The `js/framework.js` file is useful when you need to tap -into some of the functionality and properties of the framework when working in JavaScript. +- A JavaScript package that has versions of some of the Sass functions (i.e. `calculateRem`, `lightenDarkenColor` ) as well as an object +(`framework`) that holds properties for spacing, breakpoints, etc. The `js/framework.js` file is useful when you need to tap +into some of the functionality and properties of the framework when working in JavaScript. The JavaScript package also has a set of styled components (`js/styled/linkHovers.js`) that are used to set hover styles. +--- +> ***Note of Caution*** +> +> While it is possible to override the styling provided by this CSS framework or the individual Themes components by applying more specific selectors, this is not recommended. Because the CSS framework and Themes components are subject to change, it is possible that CSS selector overrides will break as elements, class names, IDs and other references change within these components. If you require custom styling of a component, we recommend writing a custom component to handle your needs. If you are currently overriding any styling on the Themes website, we invite you to submit your use case to the [Themes Ideas Board](https://ideas.arcpublishing.com/) so it can be considered as a future roadmap item. +--- + ### Getting Started: To use Theme CSS within a feature pack repository, it must be configured through a file in the root of the repo called `blocks.json`. This is a file that Fusion (Hydrate versions) knows to look for and run specific internal build commands to bring everything @@ -84,33 +90,34 @@ Here is an example of what a the CSS setup in the `block.json` might look like. } } ``` + ### Custom Block Developers -If you are creating custom blocks for your site and plan on using news-theme-css as a dependency, +If you are creating custom blocks for your site and plan on using news-theme-css as a dependency, then in addition to configuring blocks.json as per the section above, you will need to follow some additional steps to ensure this framework is available in your code. There are two different scenarios in custom development that pertain to using this framework: Developing custom components in a feature pack and developing custom -components in a separate repository. +components in a separate repository. #### Developing custom components in a feature pack -If you are developing your custom components directly in your feature pack, then as long as you have set +If you are developing your custom components directly in your feature pack, then as long as you have set up your blocks.json to use the CSS Framework, you do not explicitly add the framework to any -package.json file or directly import the framework's sass files into your component's sass file. Fusion takes +package.json file or directly import the framework's sass files into your component's sass file. Fusion takes care of properly importing the CSS Framework into component's sass file as well as setting theme values. However. -if you require any of the functionality from the framework's JavaScript assets, then you will need to +if you require any of the functionality from the framework's JavaScript assets, then you will need to import that into your component's JavaScript. For example, if you needed the `framework` object, you would import that in your JS or JSX file like this: `import { framework } from '@wpmedia/news-theme-css/js/framework';` #### Developing custom components in a separate repository -If you are developing your custom components in a separate repository, then as long as you have set -up your blocks.json to use the css framework in the feature pack that will leverage your component repository, -you still do not need to directly import the framework's sass files -into your component's sass file. However, you will need to add the CSS Framework as a dependency to your external -component's package.json file. +If you are developing your custom components in a separate repository, then as long as you have set +up your blocks.json to use the css framework in the feature pack that will leverage your component repository, +you still do not need to directly import the framework's sass files +into your component's sass file. However, you will need to add the CSS Framework as a dependency to your external +component's package.json file. -Note: When adding the dependency to package.json, ensure that it is the same version -that you specify for `cssFramework` in blocks.json. +Note: When adding the dependency to package.json, ensure that it is the same version +that you specify for `cssFramework` in blocks.json. -If you require any of the functionality from the framework's -JavaScript assets, then you will need to import that into your component's JavaScript. +If you require any of the functionality from the framework's +JavaScript assets, then you will need to import that into your component's JavaScript. For example, if you needed the `framework` object, you would import that in your JS or JSX file like this: `import { framework } from '@wpmedia/news-theme-css/js/framework';` diff --git a/styleguide/index.html b/styleguide/index.html index 4e31ea8..07bbd74 100644 --- a/styleguide/index.html +++ b/styleguide/index.html @@ -252,6 +252,12 @@

Overview

into some of the functionality and properties of the framework when working in JavaScript. The JavaScript package also has a set of styled components (js/styled/linkHovers.js) that are used to set hover styles. +
+
+

Note of Caution

+

While it is possible to override the styling provided by this CSS framework or the individual Themes components by applying more specific selectors, this is not recommended. Because the CSS framework and Themes components are subject to change, it is possible that CSS selector overrides will break as elements, class names, IDs and other references change within these components. If you require custom styling of a component, we recommend writing a custom component to handle your needs. If you are currently overriding any styling on the Themes website, we invite you to submit your use case to the Themes Ideas Board so it can be considered as a future roadmap item.

+
+

Getting Started:

To use Theme CSS within a feature pack repository, it must be configured through a file in the root of the repo called blocks.json. This is a file that Fusion (Hydrate versions) knows to look for and run specific internal build commands to bring everything @@ -365,7 +371,7 @@

Developing custom components in a separate repository

Note: When adding the dependency to package.json, ensure that it is the same version that you specify for cssFramework in blocks.json.

If you require any of the functionality from the framework's -JavaScript assets, then you will need to import that into your component's JavaScript.
+JavaScript assets, then you will need to import that into your component's JavaScript. For example, if you needed the framework object, you would import that in your JS or JSX file like this: import { framework } from '@wpmedia/news-theme-css/js/framework';