@codenhub/styles 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +25 -0
  3. package/README.md +22 -9
  4. package/dist/components.css +1 -1
  5. package/dist/index.css +1 -1
  6. package/dist/theme.css +1 -1
  7. package/package.json +15 -10
  8. package/src/components/button.css +155 -0
  9. package/src/components/feedback.css +214 -0
  10. package/src/components/form.css +303 -0
  11. package/src/components/index.css +9 -0
  12. package/src/components/loader.css +56 -0
  13. package/src/components/surface.css +6 -0
  14. package/src/components/tooltip.css +60 -0
  15. package/src/index.css +5 -91
  16. package/src/overrides.css +76 -0
  17. package/src/theme.css +116 -11
  18. package/src/typography.css +30 -0
  19. package/src/utilities.css +40 -0
  20. package/.docs/accessibility.md +0 -53
  21. package/.docs/classes.md +0 -188
  22. package/.docs/index.md +0 -66
  23. package/.docs/roadmap.md +0 -63
  24. package/.docs/tests.md +0 -128
  25. package/.docs/tokens.md +0 -100
  26. package/src/components.css +0 -657
package/.docs/classes.md DELETED
@@ -1,188 +0,0 @@
1
- # @codenhub/styles Classes
2
-
3
- **Status:** IMPLEMENTED
4
- **Last updated:** 2026-06-18
5
- **Scope:** Public helper classes for `@codenhub/styles`.
6
-
7
- Helper classes are CSS-only. They provide presentation and state styling, not semantics or behavior.
8
-
9
- ## Layout
10
-
11
- | Class | Purpose |
12
- | ------------------------------------------------- | ------------------------------------------------------------------------ |
13
- | `.sect` | Responsive section wrapper with centered column layout and page gutters. |
14
- | `.sect-container` | Centered section container using `--container-max`. |
15
- | `.sect-inn` | Section inner container using the same behavior as `.sect-container`. |
16
- | `.sect-container.narrow`, `.sect-inn.narrow` | Use `--container-narrow`. |
17
- | `.sect-container.wide`, `.sect-inn.wide` | Use `--container-wide`. |
18
- | `.left`, `.right`, `.center` on container helpers | Align container contents. |
19
- | `.stack` | Vertical flex stack using `--layout-stack-gap`. |
20
- | `.stack.tight` | Smaller stack gap. |
21
- | `.stack.loose` | Larger stack gap. |
22
- | `.cluster` | Wrapping horizontal flex cluster using `--layout-cluster-gap`. |
23
- | `.cluster.between` | Cluster with `space-between` alignment. |
24
- | `.auto-grid` | Responsive auto-fit grid using `--layout-grid-min`. |
25
-
26
- ## Surfaces
27
-
28
- | Class | Purpose |
29
- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
30
- | `.card` | Raised content surface with border, radius, padding, shadow, and column layout. |
31
- | `.panel` | Subtle foreground surface with the same structure as `.card`. |
32
- | `.card.interactive`, `.panel.interactive` | Adds pointer cursor and hover affordance. |
33
- | `.card[data-state="open"]`, `.panel[data-state="open"]` | Applies open-state border/affordance. |
34
- | `.empty-state` | Centered empty-state layout with muted color. |
35
-
36
- ## Buttons
37
-
38
- Use `.btn` with one optional intent class, one optional presentation class, optional size class, and optional state.
39
-
40
- Intent classes map color tokens into button tone slots. Presentation classes own how those slots become background, text, border, hover, and spinner styles.
41
-
42
- Intent classes:
43
-
44
- | Class | Meaning |
45
- | ----------------------------------- | ------------------------------ |
46
- | `.primary` | Primary action. |
47
- | `.secondary` | Secondary/accent action. |
48
- | `.success` | Successful or positive action. |
49
- | `.warning` | Warning/caution action. |
50
- | `.destructive`, `.danger`, `.error` | Destructive or error action. |
51
- | `.info` | Informational action. |
52
-
53
- Presentation and size classes:
54
-
55
- | Class | Purpose |
56
- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
57
- | `.out` | Transparent button with intent readable-tone border and text. |
58
- | `.ghost` | Transparent button with intent readable-tone text and soft hover. |
59
- | `.soft` | Low-emphasis filled button using intent subtle surface and strong text tones. |
60
- | `.pill` | Fully rounded button corners (`border-radius: 9999px`). |
61
- | `.fill` with `.out` | Filled hover treatment using intent color and contrast text. |
62
- | `.sm` | Smaller button. |
63
- | `.lg` | Larger button. |
64
- | `.icon` | Square icon button. Use an accessible name in HTML. |
65
- | `.loading` | Loading state. Hides text and shows CSS spinner. |
66
- | `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling. |
67
-
68
- Examples:
69
-
70
- ```html
71
- <button class="btn primary">Primary</button>
72
- <button class="btn success out">Success outline</button>
73
- <button class="btn warning soft">Warning soft</button>
74
- <button class="btn destructive ghost">Danger ghost</button>
75
- <button class="btn icon primary" aria-label="Create">+</button>
76
- <button class="btn primary loading" disabled>Saving</button>
77
- ```
78
-
79
- `.loading` is a state, not a color or presentation class. Prefer combining it with disabled behavior so users cannot trigger duplicate work. Loading buttons keep only opacity and transform transitions active so spinner and surface colors stay synchronized when theme tokens change.
80
-
81
- ## Forms
82
-
83
- | Class or Selector | Purpose |
84
- | --------------------------------------------------------------------- | ----------------------------------- |
85
- | `.field` | Vertical field wrapper. |
86
- | `.label` | Form label text. |
87
- | `.hint` | Secondary helper text. |
88
- | `.error` inside `.field` except `.btn.error`, `.field-error` | Destructive helper text. |
89
- | `.ipt` | Input control styling. |
90
- | `.textarea` | Textarea control styling. |
91
- | `.select` | Select control styling. |
92
- | `input[type="checkbox"].checkbox` | Custom checkbox control styling. |
93
- | `input[type="checkbox"].switch` | Custom switch control styling. |
94
- | `[aria-invalid="true"]` on controls | Destructive border and focus color. |
95
- | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` on controls | Disabled styling. |
96
-
97
- `.checkbox` and `.switch` accept the same intent classes as buttons to set the checked color:
98
-
99
- | Class | Meaning |
100
- | ----------------------------------- | ------------------ |
101
- | _(default)_ | Primary color. |
102
- | `.success` | Success color. |
103
- | `.warning` | Warning color. |
104
- | `.destructive`, `.danger`, `.error` | Destructive color. |
105
- | `.info` | Info color. |
106
-
107
- Example:
108
-
109
- ```html
110
- <label class="field">
111
- <span class="label">Email</span>
112
- <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
113
- <span class="error" id="email-error">Enter a valid email.</span>
114
- </label>
115
- <label style="display: flex; gap: 0.5rem; align-items: center">
116
- <input type="checkbox" class="checkbox success" />
117
- <span>Accept terms</span>
118
- </label>
119
- <label style="display: flex; gap: 0.5rem; align-items: center">
120
- <input type="checkbox" class="switch destructive" />
121
- <span>Enable</span>
122
- </label>
123
- ```
124
-
125
- `.progress` also accepts the same intent classes to color the fill bar:
126
-
127
- ## Feedback
128
-
129
- | Class | Purpose |
130
- | ----------- | ----------------------------------------------------- |
131
- | `.alert` | Inline feedback surface. |
132
- | `.banner` | Full-width feedback strip. No side borders. |
133
- | `.toast` | Fixed overlay feedback surface. |
134
- | `.badge` | Compact status pill. |
135
- | `.spinner` | Inline loading spinner. |
136
- | `.skeleton` | Ambient loading placeholder. |
137
- | `.progress` | Progress track. Fill element uses `--progress-value`. |
138
-
139
- Feedback helpers accept the same intent classes as buttons: `.success`, `.warning`, `.destructive`, `.danger`, `.error`, and `.info`.
140
-
141
- `.banner` extends `.alert` with `border-radius: 0` and removes side borders, making it suitable for full-width application-level feedback strips. `.toast` uses `--elevation-overlay` for its shadow.
142
-
143
- Examples:
144
-
145
- ```html
146
- <div class="alert success" role="status">Saved successfully.</div>
147
- <div class="banner warning" role="status">Your session expires in 5 minutes.</div>
148
- <div class="toast info" role="status">Ready.</div>
149
- <span class="badge warning">Queued</span>
150
- <span class="spinner" aria-hidden="true"></span>
151
- <div class="progress" aria-label="Upload progress"><span style="--progress-value: 64%"></span></div>
152
- <div class="progress success" aria-label="Upload progress"><span style="--progress-value: 64%"></span></div>
153
- ```
154
-
155
- ## Tooltips
156
-
157
- | Class or Attribute | Purpose |
158
- | ---------------------------------- | ------------------------------------------------------------ |
159
- | `.tooltip` | Tooltip host. Uses `data-tooltip` as pseudo-element content. |
160
- | `.tooltip.icon` | Circular icon-style tooltip host. |
161
- | `[data-tooltip-position="top"]` | Positions tooltip above host. |
162
- | `[data-tooltip-position="bottom"]` | Positions tooltip below host. |
163
- | `[data-tooltip-position="left"]` | Positions tooltip left of host. |
164
- | `[data-tooltip-position="right"]` | Positions tooltip right of host. |
165
- | No `data-tooltip-position` | Defaults to top placement. |
166
- | `[data-state="open"]` | Shows tooltip without hover. |
167
-
168
- Example:
169
-
170
- ```html
171
- <button class="tooltip icon" data-tooltip="More details" data-tooltip-position="right" aria-label="More details">
172
- ?
173
- </button>
174
- ```
175
-
176
- CSS pseudo-element tooltips are presentational. They are not a complete accessible tooltip implementation by themselves.
177
-
178
- ## Typography Utilities
179
-
180
- | Class | Purpose |
181
- | ---------------- | ------------------------------ |
182
- | `.text-display` | Large display headings. |
183
- | `.text-title-lg` | Large section titles. |
184
- | `.text-title` | Default section titles. |
185
- | `.text-title-sm` | Smaller titles or card titles. |
186
- | `.text-label-lg` | Large label text. |
187
- | `.text-label` | Default label text. |
188
- | `.text-body` | Default body copy. |
package/.docs/index.md DELETED
@@ -1,66 +0,0 @@
1
- # @codenhub/styles Overview
2
-
3
- **Status:** IMPLEMENTED
4
- **Last updated:** 2026-06-18
5
- **Scope:** `@codenhub/styles` package.
6
-
7
- `@codenhub/styles` is a CSS-only styling foundation for Codenhub interfaces. It provides tokens, base styles, typography utilities, layout helpers, component helper classes, and Tailwind CSS v4 source entrypoints.
8
-
9
- The package has no JavaScript runtime. It does not create DOM nodes, attach event listeners, manage focus, validate forms, dismiss toasts, or provide framework components.
10
-
11
- ## Public Entrypoints
12
-
13
- | Path | Contents |
14
- | -------------------------------- | --------------------------------------------------------------------- |
15
- | `@codenhub/styles` | Full compiled stylesheet: theme, base styles, components, typography. |
16
- | `@codenhub/styles/theme` | Compiled theme tokens and dark-mode variables. |
17
- | `@codenhub/styles/components` | Compiled theme tokens plus component classes. |
18
- | `@codenhub/styles/tw` | Tailwind v4 source for theme, base styles, components, and utilities. |
19
- | `@codenhub/styles/tw/theme` | Tailwind v4 source for theme tokens and custom dark variant. |
20
- | `@codenhub/styles/tw/components` | Tailwind v4 source for theme tokens and component classes. |
21
-
22
- `components` entrypoints include theme tokens because component classes depend on those variables.
23
-
24
- ## Class Model
25
-
26
- Helper classes are designed as small composable CSS contracts:
27
-
28
- - Intent classes define meaning, such as `.primary`, `.success`, `.warning`, `.destructive`, and `.info`.
29
- - Presentation classes define treatment, such as `.out`, `.ghost`, `.soft`, `.sm`, `.lg`, and `.icon`.
30
- - State classes or attributes define current state, such as `.loading`, `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, `[aria-invalid="true"]`, and `[data-state="open"]`.
31
-
32
- Button example:
33
-
34
- ```html
35
- <button class="btn success out">Success outline</button>
36
- <button class="btn destructive ghost">Danger ghost</button>
37
- <button class="btn primary loading" disabled>Saving</button>
38
- ```
39
-
40
- `out`, `ghost`, and `soft` are presentation choices. They consume active intent tone slots instead of carrying a fixed color intent; for example, `.btn.success.soft` uses success subtle and strong tones.
41
-
42
- ## Token Model
43
-
44
- Component classes use public foundation tokens for shape, motion, focus, surface, and state behavior. Internal scoped variables may exist to compose class variants, but they are not the public customization contract.
45
-
46
- Example future-ready profile shape:
47
-
48
- ```css
49
- .custom-profile {
50
- --radius-surface: 1.25rem;
51
- --elevation-low: 0 24px 60px rgb(0 0 0 / 0.18);
52
- --motion-duration-normal: 240ms;
53
- }
54
- ```
55
-
56
- Aesthetic profile classes such as `.glassmorphism` or `.brutalism` are not part of v0.0.2. v0.0.2 provides the token foundation that makes them possible later.
57
-
58
- ## Documentation Map
59
-
60
- | Document | Purpose |
61
- | ----------------------------------- | --------------------------------------------------------- |
62
- | [Tokens](./tokens.md) | Theme and foundation variable contracts. |
63
- | [Classes](./classes.md) | Public helper class behavior and composition rules. |
64
- | [Accessibility](./accessibility.md) | CSS accessibility hooks and responsibilities outside CSS. |
65
- | [Tests](./tests.md) | Build and browser validation strategy. |
66
- | [Roadmap](./roadmap.md) | Draft direction and durable planning context. |
package/.docs/roadmap.md DELETED
@@ -1,63 +0,0 @@
1
- # Roadmap
2
-
3
- **Status:** APPROVED
4
- **Last updated:** 2026-06-18
5
- **Scope:** `@codenhub/styles` package direction.
6
-
7
- ## Purpose
8
-
9
- This roadmap tracks durable direction for `@codenhub/styles`. It captures styling-system improvements that should guide future changes without turning this document into a release checklist.
10
-
11
- ## Recently Completed
12
-
13
- - Published the v0.0.2 foundation: tokens, helper classes, accessibility notes, and test strategy.
14
- - Added package-shipped `.docs` files and kept the README focused on quickstart usage plus links to durable docs.
15
- - Added foundational design tokens for colors, layout, radius, motion, focus, shadows, layering, and dark mode.
16
- - Added primary and secondary companion tokens (`--color-primary-subtle`, `--color-primary-strong`, `--color-accent-subtle`, `--color-accent-strong`).
17
- - Expanded helper classes for layout, surfaces, buttons, forms, feedback, loading indicators, progress, empty states, and tooltips.
18
- - Added preview and browser coverage for compiled CSS and Tailwind source CSS consumer paths.
19
- - Refactored component helpers toward Tailwind-first source usage with `@apply` for static utility-like styling.
20
- - Preserved composable button intent classes and presentation classes, including `.btn.error` inside `.field`.
21
- - Reduced selector leakage by nesting related component styles where CSS nesting clearly scopes variants, states, pseudo-elements, and descendants to their owning helper class.
22
- - Improved button presentation compatibility: button intents map color tone variants into scoped button slots, while `.ghost`, `.out`, and `.soft` own how those slots become presentation styles.
23
- - Added semantic hover tokens for success, warning, destructive, and info intents.
24
- - Renamed companion tone tokens from light/dark to subtle/strong so their names describe role instead of theme luminance.
25
- - Kept loading buttons from animating color-related transitions so spinner and surface colors stay synchronized during theme changes.
26
- - Added `.soft` and `.pill` as formally supported presentation classes with consistent docs and tests.
27
- - Added `.banner` as a full-width, border-x-0 static feedback surface that extends the `.alert` token foundation.
28
- - Refactored `.toast` so it shares the feedback token foundation with `.alert`, adds placement and overlay-specific treatment, and uses `--elevation-overlay` for its shadow.
29
- - Split motion tokens by use case: `--motion-duration-fast` for buttons and inputs, `--motion-duration-normal` for layout and modals, `--motion-duration-slow` for skeleton and progress transitions.
30
- - Replaced raw shadow tokens with semantic elevation tokens: `--elevation-low`, `--elevation-mid`, `--elevation-high`, `--elevation-overlay`.
31
- - Added an internal theme toggle to the preview, fixed in the bottom-right corner.
32
- - Tightened public token roles by removing legacy root tokens and treating component-scoped variables as internal implementation details.
33
- - Updated semantic contrast tokens so filled intent buttons meet 3:1 UI component contrast requirements.
34
- - Added regression coverage for filled semantic button contrast, presentation/intent tone slot composition, loading transition behavior, and legacy token removal.
35
-
36
- ## Planned
37
-
38
- - Consider adding more presentation classes for buttons (e.g. `loading` state enhancements) once component APIs stabilize.
39
- - Add more explicit compatibility tests for intent and presentation combinations when new combinations are supported.
40
-
41
- ## Later / Possible
42
-
43
- - Evaluate whether `@codenhub/theme` should provide theme-toggle behavior if the need grows beyond a preview helper.
44
-
45
- ## Not Planned
46
-
47
- - Aesthetic profile classes such as `.glassmorphism` or `.brutalism` are not planned for the current foundation work. The package should first improve token roles, composition behavior, accessibility hooks, and helper compatibility.
48
- - Public JavaScript behavior is not planned for `@codenhub/styles` right now. Toast dismissal, focus management, and app-level theme state remain outside the CSS package unless a future package decision changes the runtime surface.
49
-
50
- ## Notes
51
-
52
- - Prefer scoped CSS nesting when it improves containment, but do not nest only for style. Top-level helper classes are still appropriate when they are intentional public contracts.
53
- - Presentation classes should document unsupported combinations instead of silently producing inaccessible or visually broken output.
54
- - If toasts become dismissible in examples or docs, the dismissal behavior must be supplied by a consumer or by a separate runtime package, not implied by CSS alone.
55
- - Color intent tokens own semantic tone values. Components should consume those tokens through scoped slots instead of adding broad theme-specific branches.
56
-
57
- ## References
58
-
59
- - [Overview](./index.md)
60
- - [Tokens](./tokens.md)
61
- - [Classes](./classes.md)
62
- - [Accessibility](./accessibility.md)
63
- - [Tests](./tests.md)
package/.docs/tests.md DELETED
@@ -1,128 +0,0 @@
1
- # Styles Test Strategy
2
-
3
- **Status:** APPROVED
4
- **Last updated:** 2026-06-16
5
- **Scope:** `@codenhub/styles` package test strategy.
6
-
7
- ## Goal
8
-
9
- Validate `@codenhub/styles` before publishing changes across both supported consumer paths:
10
-
11
- - Ready-to-import compiled CSS.
12
- - Tailwind CSS build-time source CSS.
13
-
14
- Keep tests package-local and focused on visual confidence plus build compatibility.
15
-
16
- ## Structure
17
-
18
- ```text
19
- packages/styles/
20
- tests/
21
- preview/
22
- vanilla/
23
- build/
24
- browser/
25
- scripts/
26
- ```
27
-
28
- ## `tests/preview`
29
-
30
- Shared manual and automated preview page for both supported consumer paths.
31
-
32
- Open with one of these URLs when running the package dev server:
33
-
34
- ```text
35
- http://localhost:5173/tests/preview/index.html?env=vanilla
36
- http://localhost:5173/tests/preview/index.html?env=build
37
- ```
38
-
39
- The page loads `tests/vanilla/output.css` for `env=vanilla` and `tests/build/output.css` for `env=build`.
40
-
41
- The floating environment toggle switches the `env` query value between `vanilla` and `build`. Its tooltip names the target environment with `See build` or `See vanilla`.
42
-
43
- Cover:
44
-
45
- - Tokens in light and dark mode.
46
- - Typography utilities.
47
- - Buttons: intent, presentation, disabled, and loading states.
48
- - Layout helpers, surfaces, forms, feedback, tooltips, and sections.
49
- - Selection and base styles.
50
- - Tailwind token utilities, dark variants, and responsive variants.
51
-
52
- Purpose: keep one HTML fixture while validating both real CSS outputs.
53
-
54
- ## `tests/vanilla`
55
-
56
- Compiled CSS output for vanilla consumers.
57
-
58
- Use built package CSS only:
59
-
60
- ```css
61
- @import "../../dist/index.css";
62
- ```
63
-
64
- Purpose: confirm canonical `@codenhub/styles` output looks right with no Tailwind consumer build.
65
-
66
- ## `tests/build`
67
-
68
- Build validation for Tailwind consumers.
69
-
70
- Use source entrypoint:
71
-
72
- ```css
73
- @import "tailwindcss";
74
- @import "@codenhub/styles/tw";
75
-
76
- @source "../preview/index.html";
77
- ```
78
-
79
- Cover:
80
-
81
- - Tailwind can process package source.
82
- - Token utilities work, such as `bg-background`, `text-text`, `font-default`.
83
- - Dark variant works with `.dark`.
84
- - Component classes build correctly.
85
- - Responsive token variants work.
86
-
87
- Purpose: confirm `@codenhub/styles/tw` works in consumer Tailwind builds.
88
-
89
- ## `tests/browser`
90
-
91
- Cross-browser automation for visual and computed-style confidence.
92
-
93
- Use Playwright by default.
94
-
95
- Tests load the same preview page twice with different `env` query values.
96
-
97
- Cover:
98
-
99
- - Chromium.
100
- - Firefox.
101
- - WebKit.
102
- - Page load assertions.
103
- - Key computed style assertions.
104
- - Optional screenshots for visual review.
105
-
106
- Purpose: catch browser-specific CSS regressions before publishing changes.
107
-
108
- ## Scripts
109
-
110
- Default package checks:
111
-
112
- ```json
113
- {
114
- "test": "pnpm typecheck && pnpm test:build && pnpm test:visual",
115
- "test:build": "pnpm build && pnpm test:build:vanilla && pnpm test:build:tw",
116
- "test:visual": "playwright test",
117
- "dev": "node ./scripts/dev.js"
118
- }
119
- ```
120
-
121
- `pnpm dev` starts a local static server and watches both CSS test builds.
122
-
123
- ## Priority
124
-
125
- 1. Keep `tests/preview` as the single shared HTML fixture.
126
- 2. Keep `tests/vanilla` for compiled CSS output.
127
- 3. Keep `tests/build` for Tailwind source build validation.
128
- 4. Keep `tests/browser` for Playwright cross-browser validation.
package/.docs/tokens.md DELETED
@@ -1,100 +0,0 @@
1
- # @codenhub/styles Tokens
2
-
3
- **Status:** IMPLEMENTED
4
- **Last updated:** 2026-06-18
5
- **Scope:** Public CSS variable contract for `@codenhub/styles`.
6
-
7
- Tokens are CSS custom properties. Default values apply by default. `.dark` may override any token value for that subtree.
8
-
9
- ```html
10
- <section class="dark">
11
- <article class="card">Dark token subtree</article>
12
- </section>
13
- ```
14
-
15
- ## Color Tokens
16
-
17
- | Token | Purpose |
18
- | ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
19
- | `--color-primary` | Primary action/content color. |
20
- | `--color-primary-contrast` | Text/icon color on primary filled surface. |
21
- | `--color-primary-hover` | Primary hover state. |
22
- | `--color-primary-subtle` | Low-emphasis companion tone for primary. Use as soft surface or subtle background. |
23
- | `--color-primary-strong` | High-emphasis companion tone for primary. Use as readable text, icon, or border on subtle surfaces. |
24
- | `--color-accent` | Secondary/accent surface. |
25
- | `--color-accent-contrast` | Text/icon color on accent filled surface. |
26
- | `--color-accent-hover` | Accent hover state. |
27
- | `--color-accent-subtle` | Low-emphasis companion tone for accent. Use as soft surface or subtle background. |
28
- | `--color-accent-strong` | High-emphasis companion tone for accent. Use as readable text, icon, or border on subtle surfaces. |
29
- | `--color-border` | Default border color. |
30
- | `--color-border-hover` | Interactive border color. |
31
- | `--color-background` | Page and default raised surface background. |
32
- | `--color-foreground` | Subtle raised foreground surface. |
33
- | `--color-surface` | Nested or muted surface. |
34
- | `--color-text` | Primary text color. |
35
- | `--color-text-secondary` | Secondary text color. |
36
- | `--color-success` | Success state color. |
37
- | `--color-success-contrast` | Text/icon color on success filled surface. Meets 3:1 UI component contrast against `--color-success`. |
38
- | `--color-success-hover` | Success hover tone. |
39
- | `--color-success-subtle` | Low-emphasis companion tone for success. |
40
- | `--color-success-strong` | High-emphasis companion tone for success. |
41
- | `--color-warning` | Warning state color. |
42
- | `--color-warning-contrast` | Text/icon color on warning filled surface. Meets 3:1 UI component contrast against `--color-warning`. |
43
- | `--color-warning-hover` | Warning hover tone. |
44
- | `--color-warning-subtle` | Low-emphasis companion tone for warning. |
45
- | `--color-warning-strong` | High-emphasis companion tone for warning. |
46
- | `--color-destructive` | Destructive/error state color. |
47
- | `--color-destructive-contrast` | Text/icon color on destructive filled surface. Meets 3:1 UI component contrast against `--color-destructive`. |
48
- | `--color-destructive-hover` | Destructive hover tone. |
49
- | `--color-destructive-subtle` | Low-emphasis companion tone for destructive. |
50
- | `--color-destructive-strong` | High-emphasis companion tone for destructive. |
51
- | `--color-info` | Informational state color. |
52
- | `--color-info-contrast` | Text/icon color on info filled surface. Meets 3:1 UI component contrast against `--color-info`. |
53
- | `--color-info-hover` | Info hover tone. |
54
- | `--color-info-subtle` | Low-emphasis companion tone for info. |
55
- | `--color-info-strong` | High-emphasis companion tone for info. |
56
-
57
- > **Intent token contract**: color intent tokens own meaning and tone variants. Components map an intent palette into scoped component slots, and presentation classes decide which slots to consume. Theme changes belong in token values such as `.dark`, not broad component-level theme checks. Component-level theme handling should exist only when a component has an internal structure that cannot be expressed through the token palette alone.
58
-
59
- ## Foundation Tokens
60
-
61
- Foundation tokens are not aliases for one color. They define layout, shape, motion, focus, depth, and layering behavior used by helper classes.
62
-
63
- | Token | Purpose |
64
- | -------------------------- | ---------------------------------------------------------------------------- |
65
- | `--font-default` | Default app font family. |
66
- | `--container-narrow` | Narrow content width. |
67
- | `--container-max` | Default content width. |
68
- | `--container-wide` | Wide content width. |
69
- | `--layout-gutter` | Responsive inline page padding. |
70
- | `--layout-section-block` | Responsive section vertical padding. |
71
- | `--layout-stack-gap` | Default vertical stack gap. |
72
- | `--layout-cluster-gap` | Default horizontal/wrapped cluster gap. |
73
- | `--layout-grid-min` | Minimum column width for `.auto-grid`. |
74
- | `--radius-control` | Radius for buttons, inputs, tooltips, and compact UI. |
75
- | `--radius-surface` | Radius for cards, panels, and alerts. |
76
- | `--radius-overlay` | Radius for overlays such as toasts. |
77
- | `--control-height` | Default minimum height for controls. |
78
- | `--border-width` | Default border width. |
79
- | `--elevation-low` | Elevation for surface-level components such as cards and panels. |
80
- | `--elevation-mid` | Elevation for elevated components such as dropdowns and floating containers. |
81
- | `--elevation-high` | Elevation for tooltips and inline overlays. |
82
- | `--elevation-overlay` | Elevation for full-screen overlays and toasts. |
83
- | `--focus-ring` | Focus-visible ring color. |
84
- | `--focus-ring-offset` | Focus-visible outline offset. |
85
- | `--focus-ring-width` | Focus-visible outline/ring width. |
86
- | `--motion-duration-fast` | Fast transition for buttons and input interactions (`120ms`). |
87
- | `--motion-duration-normal` | Normal transition for layout, modals, and banners (`200ms`). |
88
- | `--motion-duration-slow` | Slow animation for skeleton loaders and progress bars (`400ms`). |
89
- | `--motion-ease` | Default easing curve. |
90
- | `--backdrop-overlay` | Backdrop filter value for overlay-like surfaces. |
91
- | `--z-popover` | Popover/tooltip z-index. |
92
- | `--z-toast` | Toast z-index. |
93
- | `--breakpoint-xs` | Extra-small Tailwind responsive breakpoint. |
94
- | `--breakpoint-2xl` | Extended large Tailwind responsive breakpoint. |
95
-
96
- ## Component Internals
97
-
98
- Component classes may define scoped implementation variables such as `--button-*`, `--surface-*`, `--control-*`, `--feedback-*`, and `--tooltip-*`. These variables are internal wiring for class composition and are not the public token contract.
99
-
100
- Consumers should customize broad behavior through color, foundation, motion, elevation, radius, layout, and focus tokens first. The only supported component-scoped input is `--progress-value` on the child fill element inside `.progress`, because consumers must provide a value such as `64%`.