building-design-systemslisted
Install: claude install-skill wiolett-industries/foss-design
# Building Design Systems
A foss-design system lives in `.design/system/` and does two jobs at once: it is the **source of truth every canvas screen is styled with** (tokens become Tailwind v4 utilities, components are imported with `@system/components/...`), and it is a **browsable style guide** in the local viewer at `/system` (colors, typography, spacing and shape, motion, components with live specimens, guidelines, assets).
```
.design/system/
system.json name, description, web fonts, optional custom stylesheet
tokens.css CSS variables: light, dark, and the @theme mapping to Tailwind
components/ real components screens import (@system/components/button)
specimens/ one page per component, showing every variant and state
guidelines/ Markdown pages: principles, voice, layout, patterns
assets/ logos, icons, font files, imagery
```
Full format: [System format](references/system-format.md).
## Run the CLI
```bash
command -v design >/dev/null && D=design || D="npx -y foss-design"
```
`design` exists after `npm i -g foss-design`; `npx -y foss-design` runs the same CLI without installing.
## Workflow
1. **Set up.** No `.design` yet: `$D init`. No system yet: `$D system init` scaffolds `system.json`, a starter `tokens.css`, one guideline and a `Button` component with its specimen. `--empty` scaffolds only `system.json` and `tokens.css`. The starter is a format example: replace its values with the real o