Skip to content

Commit

Permalink
[TR #117] Add docs page for organization (#166)
Browse files Browse the repository at this point in the history
This PR adds a new page of documentation to explain how we organize our css and giving an import order example.
  • Loading branch information
Jeremy-Walton authored May 22, 2023
1 parent 91e1622 commit f5fc08c
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 1 deletion.
11 changes: 10 additions & 1 deletion .storybook/preview.js
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,16 @@ const preview = {
storySort: {
order: [
'Overview',
['Introduction', 'Base Reset', 'Selective Imports', 'Tokens', 'Themes', 'Scale Overriding', 'Addons'],
[
'Introduction',
'Base Reset',
'Organization',
'Selective Imports',
'Tokens',
'Themes',
'Scale Overriding',
'Addons',
],
'Tokens',
'Utilities',
'Components',
Expand Down
64 changes: 64 additions & 0 deletions src/stories/Overview/Organization.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
import { Meta } from '@storybook/addon-docs'

<Meta title="Overview/Organization" />

# Organization

As you use Optics, you will likely want to organize your Optics configuration into multiple files.

## Folder Structure

The recommended folder structure is to have a `main or application` file that is the root file. This file should import all of the other files in the folder.

- `/stylesheets`
- `application.scss`
- `/core`
- `/theme`
- `{name}-theme-core.scss`
- `{name}-theme-light.scss`
- `{name}-theme-dark.scss`
- `base.scss`
- `layout.scss`
- `utilities.scss`
- `/vendors`
- `{vendor-name}-overrides.scss`
- `/components`
- `/optics-overrides`
- `{component-name}.scss`
- `{component-name}.scss`
- `/general`
- `{general-name}.scss`

## Import Structure

Using the above folder structure, the application file should import all of the other files. Comments can be used to describe the purpose of each section of files.

```css
// Optics
@import '@rolemodel/optics';

// Vendors
@import 'something-from-node-modeules/something';

// Theme Customization
@import 'core/theme/{name}-theme-core';
@import 'core/theme/{name}-theme-light';
@import 'core/theme/{name}-theme-dark';

// Core Customization
@import 'core/base';
@import 'core/layout';
@import 'core/utilities';

// Vendor Customization
@import 'vendors/{vendor-name}-overrides';

// Optics Component Customization
@import 'components/optics-overrides/{component-name}';

// components
@import 'components/{component-name}';

// General Styles
@import 'general/{general-name}';
```

0 comments on commit f5fc08c

Please sign in to comment.