8pt Design System

---
name: ui-8pt-system
description: Makes interfaces follow one 8pt design system: spacing, type scale, radii, shadows, color and dark mode. It can generate design tokens, or audit and fix existing pages. Use when the user mentions a "design system", "design tokens", "inconsistent spacing", "8pt grid", "dark mode", "UI review" or "unifying the Tailwind config".
author: 8pt
---

# 8pt Design System

Outputs: `tokens.css`, `tokens.json` (plus a Tailwind config when needed) and `audit.md` (audit mode).

## 1. Ask the user first (up to 3; use the defaults if unanswered)
1. What should it do? A: create a system / B: audit and fix existing pages. Default: B if the project already has interface code, otherwise A.
2. Brand color? Default: `#4D74FF` (the full contrast-checked scale is in tokens.css).
3. Stack? Default: detect it: use the Tailwind mapping if there’s a `tailwind.config.*`, otherwise CSS variables.

## 2. Files
- `tokens.css`: the full token set (spacing, type, radii, sizes, motion, layers, brand color, light / dark semantic colors, shadows) plus base styles. Copy it straight into the project.
- `tokens.json`: the same tokens in W3C Design Tokens format, for Figma plugins / Style Dictionary.
- `reference/rules.md`: usage rules for each token type, contrast requirements, the Tailwind mapping and the audit.md structure.
- `scripts/audit_8pt.py`: the audit script (standard library only); scans CSS / HTML / JSX / TSX / Vue / Svelte for off-system values and hard-coded colors.

## 3. Flow A: create a system
1. Copy `tokens.css` into the project (e.g. `src/styles/tokens.css`) and import it first in the global entry; copy `tokens.json` to `design/tokens.json`.
2. If the user gave a new brand color: generate the 300/500/600/700 steps per section 4 of `reference/rules.md` and compute contrast (relative luminance formula (L1+0.05)/(L2+0.05)): 600 on white ≥ 4.5 and 300 on #0b0b10 ≥ 4.5; if a step fails, darken / lighten and recompute; update both the css and the json.
3. Tailwind projects: merge the config from section 6 of `reference/rules.md` into `tailwind.config`.
4. Dark mode: confirm both `<html data-theme="dark">` and the system preference switch it.
5. Build a sample page or component (one button, one input, one card) to confirm the tokens apply.

## 4. Flow B: audit and fix
1. Run `python3 scripts/audit_8pt.py <source dir> -o audit-scan.md` (the script lives in this Skill’s folder; you can also copy it into the project’s `scripts/` and run it there).
2. Manually check what the script can’t: text contrast, touch targets ≥ 44px, more than 3 type levels per screen, hard-coded white-background / black-text in dark mode, and whether `:focus-visible` is removed by `outline:none`.
3. Fix: replace values with the nearest token variable as suggested (e.g. `padding:10px 15px` → `padding:var(--space-2) var(--space-4)`); list changes with an obvious visual jump (type sizes off by ≥ 4px) and ask the user before changing them.
4. Rerun the script after fixing until every remaining item has a reason to keep it (third-party components, chart internals, pixel-level icons).
5. Write `audit.md` per section 7 of `reference/rules.md`: conclusion, scan table, manual checks, change list.

## 5. Core specs
- Spacing 0 4 8 12 16 24 32 40 48 64 80 96 128; type sizes 12 14 16 20 24 32 48 64 (line heights 16 20 24 28 32 40 56 72).
- Radii 4 8 12 16 24 full; 3 shadow levels; control heights 32 / 40 / 48.
- Contrast: body text ≥ 4.5:1, large text and non-text UI ≥ 3:1, in both light and dark.

## 6. Self-check before delivery
- [ ] tokens.css and tokens.json match (spacing, type sizes, radii and colors checked one by one).
- [ ] No hex colors or non-token px written directly in component code (rerun the audit script to confirm, or list the reasons to keep them).
- [ ] Both light and dark checked page by page, with text contrast passing.
- [ ] The focus ring is visible when tabbing with the keyboard; no animation under `prefers-reduced-motion`.
- [ ] audit.md (audit mode) has all four parts, and the change list matches the actual changes.

## 7. Don’t
- Don’t add non-token values like 13px, 15px or 18px to "match the mockup"; if one is truly needed, ask the user and add it as a token instead of scattering it through components.
- Don’t change the page’s information structure, copy or features on your own; an audit only touches styles.
- Don’t remove `:focus-visible` styles, and don’t signal error / success with color alone.
- Don’t claim "WCAG compliant" unless every item was verified; report only what you actually checked.

## 8. When you deliver, tell the user
1. What you did (create / audit) and the list of changed files.
2. Audit mode: total issues, how many fixed, items kept and why.
3. The defaults you used (brand color, stack) and the visual changes the user needs to decide on.