@deskpro/apps-components-style
v0.12.5
Published
Styling for for Deskpro Apps
Downloads
302
Readme
Deskpro Apps
CSS Styling for Deskpro Apps.
View Documentation and Examples
Goals:
- Clean component CSS.
- Components should be usable in any context on any page, even if the page has other global CSS.
- Each component must be self-contained and not rely on any other components. i.e. it should be possible to import a single component CSS file and use it without importing anything else in the library.
Non-goals:
- We are not trying to be a themeing library. i.e. we are not trying to go out of our way to allow customisation, custom variables, etc.
Development
Summary:
- Run
npm install
- Run
npm run dev
- Open
http://localhost:3000/apps-style/
in your browser - Edit CSS files in
src/
and docs indocs/
. As you edit files, the docs site above will live reload.
Prepare
- You need
node
andnpm
installed on your computer - Run
npm install
to initialize dependencies
Development
To start with, run npm run dev
to start the built-in dev server. This should open your browser at http://localhost:3000/apps-style/
with the documentation site.
As you modify CSS files in src/
and markdown documentation files in docs/
, your browser will live relaod. This makes for a really fast and smooth dev experience.
Here's an example. Say you're working on buttons:
- In your editor, open
src/components/buttons.css
anddocs/components/buttons.md
- In your browser, open
http://localhost:3000/apps-style/docs/components/buttons.html
- As you change
buttons.css
, updatebuttons.md
documentation and examples. Your browser will live-reload as you go.
Project Structure
CSS is being post-processed with PostCSS with the postcss-preset-env which enables a bunch of proposed CSS features like variables. We use Stage 0 features.
The general idea is to stay as close to "normal CSS" as we can. i.e. we want to avoid using programming logic like loops, which is why we have avoided SASS or LESS. PostCSS offers just enough convenience (e.g. nested selectors) without going overboard.
This project is linted with stylelint and a SUIT linter plugin. Refer to the documentation if you run into issues or need to tweak the config in some way.
Conventions
- You MUST use SUIT nameing conventions in this project.
- You MUST use the
dp-
namespace on all components.- Modifiers on the component don't include the namespace. E.g. it would be
.dp-Button.Button--warning
.
- Modifiers on the component don't include the namespace. E.g. it would be
- You MUST NOT define global styles or global resets.
- You MUST define 1 CSS file per element or component. The goal is to design components that can be used as-is in isolation.
- Each component MUST be completely self-defined. i.e. 1 component (aka 1 CSS file) MUST contain ALL the code necessary for that specific component. In other words, your component must not rely on external CSS code from other files or global styles.
- Each component MUST include basic styles such as fonts, sizes, etc. This project uses an auto-reset plugin which resets style properties on all components to defaults. This reduces the chance of some rogue global CSS elsewhere on the page causing a visual glitch in our components.
- Each component MUST have documentation in
docs/
that describe and demonstrate the component and any of its modifiers.
Documentation Files
The documentation pages in docs/
serve as your "development playground" while you make changes to CSS, but by the time you finish a component, it should also serve as real documentation too.
Documentation is written in Markdown. There are two special bit of fenced HTML:
- Fenced code with the language
html @preview
will render the HTML code to the browser screen and show a "toggle code" button that you can click to show the source code. This is what your examples should be written in. - Fenced code with the language
html @render
is similar, except there is no button to show the source code. So this is an escape-hatch for (rare) cases you need to render arbitrary HTML.
Most of your documentation will be written with examples in html @preview
fenced blocks. For example:
```html @preview
<button class="dp-Button">Default</button>
<button class="dp-Button Button--primary">Primary</button>
<button class="dp-Button Button--warning">Warning</button>
```
This results in three buttons being rendered to the page with "toggle code" button that will reveal that exact source code. So this is perfect for documentation to show off how to use code.
Creating new docs
When you start a new component you'll need to create a new docs file for it:
- Create a new Markdown file in
docs/components/my-component.md
. Here's an example:
---
title: My Component
---
# My Component
This is my great component.
```html @preview
<div class="dp-MyComponent">
Here's an example!
</div>
```
This new file maps directly to the URL http://localhost:3000/apps-style/docs/components/my-component.html
- To have the file listed in the sidebar, modify
website/sidebars.json
and add it.