Ludo
5bf233348d
Specs: repo-structure, 10 framework layer specs, packs, site. Changes: repo-restructure (10 tasks), css-refactor (12 tasks), legacy-import (proposal + triage categories). Supersede docs/css-refactor-plan.md in favor of OpenSpec change. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
77 lines
2.5 KiB
Markdown
77 lines
2.5 KiB
Markdown
# Spec: Tokens (Layer 01)
|
|
|
|
File: `src/layers/01-tokens.css`
|
|
|
|
## Purpose
|
|
|
|
Pure design token definitions. Aliases Open Props primitives to semantic names. Contains only `:root {}` variable declarations — no rules, no selectors, no styling.
|
|
|
|
## Open Props Dependency
|
|
|
|
ASW builds on Open Props as its primitive token source. Open Props provides:
|
|
- Color scales: `--color-0` through `--color-16`
|
|
- Size scale: `--size-1` through `--size-15`, `--size-px-1` through `--size-px-12`
|
|
- Font sizes: `--font-size-0` through `--font-size-8`
|
|
- Font weights: `--font-weight-1` through `--font-weight-9`
|
|
- Shadows: `--shadow-1` through `--shadow-6`
|
|
- Border sizes: `--border-size-1` through `--border-size-5`
|
|
- Animations, easings, gradients, and more
|
|
|
|
**Version:** tracked in `vendor/open-props/VERSION`
|
|
|
|
## Aliasing Contract
|
|
|
|
Every Open Props primitive used in the framework MUST be aliased through this file. Downstream layers (02+) MUST reference semantic aliases, never primitives.
|
|
|
|
```css
|
|
/* YES — downstream layers use this */
|
|
color: var(--text);
|
|
font-weight: var(--weight-bold);
|
|
padding: var(--space-4);
|
|
|
|
/* NO — never in layers 02+ */
|
|
color: var(--color-6);
|
|
font-weight: var(--font-weight-7);
|
|
padding: var(--size-3);
|
|
```
|
|
|
|
## Token Categories
|
|
|
|
### Colors
|
|
- `--surface`, `--surface-alt` — background colors
|
|
- `--text`, `--text-muted` — foreground colors
|
|
- `--accent`, `--accent-hover` — interactive/brand color
|
|
- `--border`, `--border-muted` — border colors
|
|
- `--code-bg`, `--code-text` — code block colors
|
|
|
|
### Spacing
|
|
- `--space-1` through `--space-7` — spacing scale
|
|
- Maps to Open Props `--size-N` scale
|
|
|
|
### Typography
|
|
- `--weight-normal`, `--weight-medium`, `--weight-semibold`, `--weight-bold`
|
|
- `--font-body`, `--font-mono` — font stacks
|
|
- `--line-height-body`, `--line-height-heading`
|
|
- `--width-prose` — max-width for readable text
|
|
|
|
### Shadows
|
|
- `--shadow-dropdown`, `--shadow-modal` — purpose-named shadows
|
|
|
|
### Focus / Interaction
|
|
- `--focus-ring-width` — keyboard focus ring width
|
|
|
|
## Scenarios
|
|
|
|
### Given a new primitive reference needed
|
|
- **When** a downstream layer needs an Open Props value
|
|
- **Then** add a semantic alias to this file first
|
|
- **And** reference only the alias in the downstream layer
|
|
|
|
### Given an unused token
|
|
- **When** auditing finds a token alias with zero references in layers 02+
|
|
- **Then** it may be removed from this file
|
|
|
|
### Given this file
|
|
- **When** inspected
|
|
- **Then** it contains only `:root {}` with `--custom-property: value;` declarations
|
|
- **And** no element selectors, no class selectors, no rules
|