Sky's CSS Toolkit
Sky’s CSS Toolkit
For full documentation, visit https://www.sky.com/toolkit
The project consists of 3 packages:
$ npm install sky-toolkit --save
:warning: Note: your Sass configuration must be set to access certain dependencies or installation will fail. Either:
node_modulesin your
includedPaths.
See sky.com/toolkit for full individual component documentation.
Because of how the Toolkit loads third party dependencies (such as sass-mq), your development environment needs:
If you’re using webpack you’ll also need:
To support IE9+, you must include the following at the top of your
index.html/ default container view.
...
For rapid prototyping and static sites, you can include our latest compiled CSS in the
of your page.We strongly advise not to use this method in live projects. Use
npminstallation to benefit from the Toolkit’s modularity and extensibility.
Alternatively, in Node.js, use
sky-toolkit's entry point to grab an automatically version-controlled link which corresponds to your app's version of Toolkit in
package.json
For example:
const { cdnUrl: skyToolkit } = require('sky-toolkit');module.exports =
<link rel="stylesheet" href="%24%7BskyToolkit%7D"> <!-- Your App's Stylesheets/Assets, for example: --> <link rel="stylesheet" href="main.css">
;
Once installed, there are 2 methods of Toolkit implementation:
A combination of compiled and Sass implementation:
sky-toolkit-corevia a CDN allows for caching across the estate, allowing for performance benefits as well as greater code consistency. If you're using Node.js, versioning is automatically taken care of via the entry point.
sky-toolkit-uimodularly via Sass avoids unused CSS bloat.
sky-toolkit-core's compiled module into your layout/template which houses the for your application.
It must be the first stylesheet defined:
Node.js - utilise the entry point to grab an automatically version-controlled link which corresponds to your app's version of Toolkit in
package.json. For example, your template file could look like:
const { skyToolkitCoreCdnUrl } = require('sky-toolkit');module.exports =
<link rel="stylesheet" href="%24%7BskyToolkitCoreCdnUrl%7D"> <!-- Your App's Stylesheets/Assets, for example: --> <link rel="stylesheet" href="main.css">
;
sky-toolkit-core/tools, not
/all.
.scssfile, include
sky-toolkit-coreat the very top:
* If you're following the **Hybrid** method above, you **must** use **`/tools`** to utilise tools and settings and avoid outputting the core./* main.scss (compiles to main.css) */ @import "sky-toolkit-core/tools";
This is required if you're extending any Toolkit styles or creating custom components.
If you're not following the Hybrid method above and you're using
Toolkit fully via Sass, you must use /all
to output the core.
/* main.scss (compiles to main.css) */
@import "sky-toolkit-core/all";
This is required by all sky-toolkit-ui
components / custom styles that
extend Toolkit.
:warning: Do not import /all
when using the Hybrid method, as it
will duplicate styles.
Following that, you can import individual
sky-toolkit-uicomponents and your own project-specific styles, for example:
/* main.scss (compiles to main.css) */
/* Change to /tools
or /all
where appropriate */
@import "sky-toolkit-core/[tools|all]";
@import "sky-toolkit-ui/components/typography"; @import "sky-toolkit-ui/components/tile"; @import "sky-toolkit-ui/components/panel";
/* Project-specific styles */ @import "components/your-component";
There is the option to import all components, however, we strongly recommend only importing the individual components required in your project.
@import "sky-toolkit-ui/all";
We love to have people contributing, but please make sure you follow our guidelines.
To get set up with a working development version of Toolkit, follow the steps detailed below:
# Clone the repo to your machine. git clone [email protected]:sky-uk/toolkit.git # Jump into your Toolkit folder. cd toolkit # Install common dependencies. npm i # Toolkit comprises several sub-packages; Lerna links them together for us. npm i -g lerna lerna bootstrap # Learn more at lernajs.io
After running these commands, you should have all the relevant code and its dependencies installed and linked up ready to go…
Note: further enhancements to preview can be found in #386
The fastest way to develop Toolkit components is to use Preview:
npm run preview
Running this command will fire up a hot reloading local environment that renders all of our components (WIP) onto a single page: * Markup – sourced from fenced code blocks within Markdown from
packages/*/docs/. * Styles - sourced from SCSS in
packages/. Additional/experimental styles can be applied in
preview/scss/.
Note: currently only supported for
sky-toolkit-uicomponents.
To render your new component in the preview environment:
Within
packages/sky-toolkit-ui/:
_all.scss:
scss @import "components/";
.mdwithin
docs/. If you're stuck, check out the provided
_template.md.
Within
preview/js/data.js:
''to the
componentsarray.
To manually compile changes across the packages into a single
build/toolkit.cssfile, run the following command:
npm run build
Toolkit follows Semantic Versioning to help manage the impact of releasing new library versions.
Before mid-June, 2017, Toolkit was split across two separate repositories:
After enough time, this strategy proved too cumbersome: managing the surface area and coordinating releases became a task in itself, even across only two repositories. To that end, we folded them into one—this one.
To view a complete history of many of the files, you will need to pass the
--followflag into your
log.
Without
--follow:
$ git log --oneline commitlint.config.jsef54c12 build(core): added comittizen, commitlint and new lerna config
With
--follow:
$ git log --oneline --follow commitlint.config.js
bf439b3 (HEAD -> commitizen, origin/commitizen) refactor(core): change wording of commit questions
ef54c12 (squash-branch) build(core): added comittizen, commitlint and new lerna config
If you run into any trouble or need support getting to grips with Toolkit, reach out in Slack or contact one of the maintainers:
|
Joe Dinsdale
💻 |
Steve Duffin
💻 |
Sam Kitson
💻 |
Stefan McCready
💻 |
Ste Allan |
| :---: | :---: | :---: | :---: | :---: |
Special thanks to the following contributors: