ui-foundations 0.3.2 → 0.6.0
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.
- package/README.md +181 -37
- package/dist/assets/icons/checkmark.svg +1 -0
- package/dist/core/index.css +8 -7
- package/dist/macros/ui.njk +203 -0
- package/dist/main.css +941 -210
- package/dist/react/accordion.js +36 -0
- package/dist/react/avatar.js +34 -0
- package/dist/react/badge.js +41 -0
- package/dist/react/button.js +4 -6
- package/dist/react/checkbox.js +21 -8
- package/dist/react/divider.js +31 -0
- package/dist/react/icon.js +8 -1
- package/dist/react/index.js +8 -0
- package/dist/react/label.js +1 -1
- package/dist/react/radio.js +45 -0
- package/dist/react/switch.js +9 -8
- package/dist/react/tabs.js +72 -0
- package/dist/react/textarea.js +38 -0
- package/dist/react/tooltip.js +25 -0
- package/dist/react/warn-dev.js +15 -0
- package/dist/tokens/css/{appearance-(modes).tokens.mode-dark.css → appearance-modes.tokens.mode-dark.css} +6 -6
- package/dist/tokens/css/{appearance-(modes).tokens.mode-light.css → appearance-modes.tokens.mode-light.css} +1 -1
- package/dist/tokens/css/{components-(ui).tokens.css → components-ui.tokens.css} +73 -32
- package/dist/tokens/css/core-primitives.tokens.css +240 -0
- package/dist/tokens/css/{semantics-(roles).tokens.css → semantics-roles.tokens.css} +1 -1
- package/dist/tokens/css/themes-brands.tokens.brand-a.css +22 -0
- package/dist/tokens/css/{themes-(brands).tokens.brand-b.css → themes-brands.tokens.brand-b.css} +9 -9
- package/dist/tokens/css/themes-brands.tokens.brand-c.css +22 -0
- package/dist/tokens/json/appearance-modes.tokens.mode-dark.json +121 -0
- package/dist/tokens/json/appearance-modes.tokens.mode-light.json +121 -0
- package/dist/tokens/json/components-ui.tokens.json +713 -0
- package/dist/tokens/json/{core-(primitives).tokens.json → core-primitives.tokens.json} +526 -410
- package/dist/tokens/json/semantics-roles.tokens.json +141 -0
- package/dist/tokens/json/themes-brands.tokens.brand-a.json +81 -0
- package/dist/tokens/json/themes-brands.tokens.brand-b.json +81 -0
- package/dist/tokens/json/themes-brands.tokens.brand-c.json +81 -0
- package/dist/tokens/tokens.yaml +2722 -499
- package/dist/tokens/ts/{appearance-(modes).tokens.mode-dark.ts → appearance-modes.tokens.mode-dark.ts} +6 -6
- package/dist/tokens/ts/{appearance-(modes).tokens.mode-light.ts → appearance-modes.tokens.mode-light.ts} +1 -1
- package/dist/tokens/ts/{components-(ui).tokens.ts → components-ui.tokens.ts} +74 -33
- package/dist/tokens/ts/core-primitives.tokens.ts +265 -0
- package/dist/tokens/ts/{semantics-(roles).tokens.ts → semantics-roles.tokens.ts} +1 -1
- package/dist/tokens/ts/themes-brands.tokens.brand-a.ts +32 -0
- package/dist/tokens/ts/{themes-(brands).tokens.brand-b.ts → themes-brands.tokens.brand-b.ts} +9 -9
- package/dist/tokens/ts/{themes-(brands).tokens.brand-a.ts → themes-brands.tokens.brand-c.ts} +9 -9
- package/dist/ui/index.css +8 -0
- package/dist/ui/patterns/accordion.css +81 -0
- package/dist/ui/patterns/avatar.css +57 -0
- package/dist/ui/patterns/badge.css +49 -0
- package/dist/ui/patterns/checkbox.css +71 -22
- package/dist/ui/patterns/divider.css +25 -0
- package/dist/ui/patterns/radio.css +109 -0
- package/dist/ui/patterns/tabs.css +71 -0
- package/dist/ui/patterns/textarea.css +50 -0
- package/dist/ui/patterns/tooltip.css +64 -0
- package/docs/README.md +38 -0
- package/docs/agentic/README.md +35 -0
- package/docs/agentic/assistant-behavior-rules.md +48 -0
- package/docs/agentic/skills/component-accessibility-audit.md +132 -0
- package/docs/agentic/skills/ux-writing-coach.md +116 -0
- package/docs/foundations/README.md +31 -0
- package/docs/foundations/foundation-001-token-layering.md +6 -0
- package/docs/foundations/foundation-002-naming-and-grouping.md +6 -0
- package/docs/foundations/foundation-003-color-semantics-and-status.md +6 -0
- package/docs/foundations/foundation-004-typography-scale-and-line-height.md +6 -0
- package/docs/foundations/foundation-005-responsive-breakpoints-and-containers.md +6 -0
- package/docs/foundations/foundation-006-z-index-layering.md +6 -0
- package/docs/foundations/foundation-007-typography-selectors-and-specificity.md +7 -1
- package/docs/foundations/foundation-008-mode-activation-and-consumer-control.md +6 -0
- package/docs/foundations/foundation-009-component-boundaries-and-utility.md +6 -0
- package/docs/foundations/foundation-010-implementation-and-pipeline-workflow.md +6 -0
- package/docs/foundations/foundation-011-branching-and-release-governance.md +6 -0
- package/docs/foundations/foundation-012-minimal-markup-and-composition.md +6 -0
- package/package.json +16 -11
- package/dist/tokens/css/core-(primitives).tokens.css +0 -127
- package/dist/tokens/css/themes-(brands).tokens.brand-a.css +0 -22
- package/dist/tokens/json/appearance-(modes).tokens.mode-dark.json +0 -182
- package/dist/tokens/json/appearance-(modes).tokens.mode-light.json +0 -182
- package/dist/tokens/json/components-(ui).tokens.json +0 -739
- package/dist/tokens/json/semantics-(roles).tokens.json +0 -203
- package/dist/tokens/json/themes-(brands).tokens.brand-a.json +0 -115
- package/dist/tokens/json/themes-(brands).tokens.brand-b.json +0 -115
- package/dist/tokens/ts/core-(primitives).tokens.ts +0 -152
- package/docs/agentic/skills/README.md +0 -51
- package/docs/agentic/skills/design-ops-specialist/SKILL.md +0 -60
- package/docs/agentic/skills/design-system-architect/SKILL.md +0 -106
- package/docs/agentic/team-ai-playbook.md +0 -226
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Assistant rules (UI Foundations)
|
|
3
|
+
status: active
|
|
4
|
+
type: agent-guide
|
|
5
|
+
---
|
|
6
|
+
|
|
1
7
|
# Assistant rules (UI Foundations)
|
|
2
8
|
|
|
3
9
|
1. Always follow foundation rules in `/docs/foundations` as the source of truth.
|
|
@@ -14,3 +20,45 @@
|
|
|
14
20
|
- This decision is independent from token work: new tokens alone are not sufficient reason for a standalone component.
|
|
15
21
|
- Apply the Snowflake check: local one-off solutions stay local; shared utility can enter the system.
|
|
16
22
|
- Source of truth: `docs/foundations/foundation-009-component-boundaries-and-utility.md`.
|
|
23
|
+
8. When creating a new component, always complete all integration surfaces:
|
|
24
|
+
- CSS pattern in `src/ui/patterns/<component>.css`
|
|
25
|
+
- Import in `src/ui/index.css`
|
|
26
|
+
- React wrapper in `src/react/<component>.js`
|
|
27
|
+
- Export in `src/react/index.js`
|
|
28
|
+
- Nunjucks macro in `site/_includes/macros/ui.njk` (source of truth; `dist/macros/ui.njk` is copied during build)
|
|
29
|
+
- Playground renderer in `site/assets/playground/renderers.js` — register the render function and add it to the `renderers` map
|
|
30
|
+
- Playground page in `site/components/<component>-playground.md` with `renderer: <component>` matching the key in the renderers map
|
|
31
|
+
- Docs page in `site/components/<component>.md`
|
|
32
|
+
- Code Connect file in `schemas/web-<component>.figma.ts`
|
|
33
|
+
Missing any of these (especially the playground renderer) will cause broken pages.
|
|
34
|
+
9. Every new component must have its own Component-layer tokens. Never reuse tokens from another component (e.g. do not use `--input-checkbox-*` for a radio).
|
|
35
|
+
- Check `dist/tokens/css/components-ui.tokens.css` for existing tokens.
|
|
36
|
+
- If the component has no tokens in Figma yet, propose new ones following the naming pattern `--<component>-<part>-<property>-<state>` and add them to `components-ui.tokens.css`, referencing only Semantic or Core tokens.
|
|
37
|
+
- This keeps components independently themeable and avoids hidden coupling.
|
|
38
|
+
10. Token alias references must point to tokens that actually exist in the system.
|
|
39
|
+
- Before adding a `$ref`, verify the target exists in `dist/tokens/css/` (Core, Modes, Semantics).
|
|
40
|
+
- Run `npm run tokens:generate` and check for "missing alias targets" warnings.
|
|
41
|
+
- Never invent Semantic/Core token names (e.g. `Color/Fill/Muted`, `Size/Spacing/50`) — use only what the system provides.
|
|
42
|
+
- If a needed Semantic token does not exist, flag it for creation in Figma first.
|
|
43
|
+
11. CSS class naming must follow the project convention: bare component name (e.g. `.slider`, `.radio`, `.checkbox`).
|
|
44
|
+
- Never prefix with `.ui-` or other namespaces.
|
|
45
|
+
- CSS patterns must be wrapped in `@layer components { }`.
|
|
46
|
+
12. React wrappers must follow the existing pattern:
|
|
47
|
+
- Named `export function` (not `export const`)
|
|
48
|
+
- No CSS imports inside React files
|
|
49
|
+
- Use `React.createElement`, not JSX
|
|
50
|
+
- Class array pattern: `const classes = ["component"]; if (className) classes.push(className);`
|
|
51
|
+
13. Docs-only UI (code-tabs, mode toggles) must use docs-specific CSS, not component tokens.
|
|
52
|
+
- The `.code-tabs-bar` and `.docs-header` button groups are styled in `site/assets/docs.css` with hardcoded docs colors.
|
|
53
|
+
- They must not inherit brand theming from `data-brand`.
|
|
54
|
+
|
|
55
|
+
## Modes
|
|
56
|
+
|
|
57
|
+
The agent operates in different modes depending on the task:
|
|
58
|
+
|
|
59
|
+
- **Implementation** → modify system
|
|
60
|
+
- **Audit** → inspect only
|
|
61
|
+
- **Pattern Discovery** → design patterns
|
|
62
|
+
- **Token Proposal** → suggest tokens
|
|
63
|
+
|
|
64
|
+
Mode-specific rules are defined in: `docs/agentic/modes/`
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Component Accessibility Audit Skill
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Create a repeatable, component-level accessibility audit workflow before implementation fixes.
|
|
6
|
+
|
|
7
|
+
Use this skill to evaluate one interactive component at a time and produce findings in a consistent format that can drive small follow-up PRs.
|
|
8
|
+
|
|
9
|
+
## Governance references (must read first)
|
|
10
|
+
|
|
11
|
+
1. `DESIGN.md`
|
|
12
|
+
2. `AGENTS.md`
|
|
13
|
+
3. `docs/playbook.md`
|
|
14
|
+
4. `docs/working-context.md`
|
|
15
|
+
5. `docs/ui-foundations-rules.md`
|
|
16
|
+
6. `docs/foundations/`
|
|
17
|
+
7. `docs/agentic/assistant-behavior-rules.md`
|
|
18
|
+
8. `IMPLEMENTATION.md`
|
|
19
|
+
|
|
20
|
+
Never contradict these sources. Prefer explicit, verifiable findings over assumptions.
|
|
21
|
+
|
|
22
|
+
## Scope
|
|
23
|
+
|
|
24
|
+
Apply this skill to interactive components (e.g., Button, Link, Input, Select, Checkbox, Radio, Switch, Tabs, Accordion, Modal, Flyout, Dropdown, Tooltip, Pagination, Show More/Show Less, Tags).
|
|
25
|
+
|
|
26
|
+
Do not use this skill to implement broad fixes in the same PR. This skill is audit-first.
|
|
27
|
+
|
|
28
|
+
## Audit workflow (repeatable)
|
|
29
|
+
|
|
30
|
+
1. **Plan**
|
|
31
|
+
- Select exactly one component target.
|
|
32
|
+
- Confirm component surfaces in scope (CSS pattern, macro/template, React wrapper, docs, tests).
|
|
33
|
+
|
|
34
|
+
2. **Collect evidence**
|
|
35
|
+
- Inspect source implementation files.
|
|
36
|
+
- Inspect usage examples and docs.
|
|
37
|
+
- Inspect test coverage.
|
|
38
|
+
- Record exact file paths and relevant lines.
|
|
39
|
+
|
|
40
|
+
3. **Run checks**
|
|
41
|
+
- Semantic HTML
|
|
42
|
+
- Accessible names
|
|
43
|
+
- Keyboard behavior
|
|
44
|
+
- Focus management
|
|
45
|
+
- ARIA/state handling
|
|
46
|
+
- Form association (where relevant)
|
|
47
|
+
- Icon-only usage
|
|
48
|
+
- Contrast/token risks
|
|
49
|
+
- Test coverage
|
|
50
|
+
- Documentation gaps
|
|
51
|
+
- Manual screen reader validation needs
|
|
52
|
+
|
|
53
|
+
4. **Score severity**
|
|
54
|
+
- Assign one severity per finding using the model below.
|
|
55
|
+
|
|
56
|
+
5. **Propose minimal fix**
|
|
57
|
+
- Suggest the smallest safe change that resolves the finding.
|
|
58
|
+
- Keep fixes scoped to one component per follow-up PR.
|
|
59
|
+
|
|
60
|
+
6. **Report**
|
|
61
|
+
- Output findings using the template in this document.
|
|
62
|
+
|
|
63
|
+
## Severity model
|
|
64
|
+
|
|
65
|
+
Use one of these labels:
|
|
66
|
+
|
|
67
|
+
- **blocker**
|
|
68
|
+
- Breaks core accessibility behavior (e.g., no accessible name, unusable keyboard path, broken form semantics, missing focus trap in modal).
|
|
69
|
+
- Should be fixed before release.
|
|
70
|
+
|
|
71
|
+
- **high**
|
|
72
|
+
- Major accessibility risk with likely user impact, but possible workaround exists.
|
|
73
|
+
- Prioritize immediately after blockers.
|
|
74
|
+
|
|
75
|
+
- **medium**
|
|
76
|
+
- Important gap or drift that reduces accessibility quality/reliability.
|
|
77
|
+
- Schedule in near-term follow-up.
|
|
78
|
+
|
|
79
|
+
- **low**
|
|
80
|
+
- Minor issue, documentation gap, or optimization with limited immediate impact.
|
|
81
|
+
- Track and resolve in routine improvements.
|
|
82
|
+
|
|
83
|
+
## Findings template
|
|
84
|
+
|
|
85
|
+
Use this exact structure for each finding:
|
|
86
|
+
|
|
87
|
+
- **Component:**
|
|
88
|
+
- **Check area:** (semantic HTML / accessible name / keyboard / focus / ARIA-state / form association / icon-only / contrast-token / tests / docs / manual SR)
|
|
89
|
+
- **Observed behavior:**
|
|
90
|
+
- **Expected behavior:**
|
|
91
|
+
- **Evidence:** (file paths + line refs)
|
|
92
|
+
- **Severity:** blocker | high | medium | low
|
|
93
|
+
- **Minimal fix strategy:**
|
|
94
|
+
- **Follow-up test need:**
|
|
95
|
+
- **Manual SR validation need:**
|
|
96
|
+
|
|
97
|
+
## Minimal-fix strategy
|
|
98
|
+
|
|
99
|
+
When proposing a fix:
|
|
100
|
+
|
|
101
|
+
1. Prefer native semantics over custom ARIA.
|
|
102
|
+
2. Change the smallest surface that safely resolves the issue.
|
|
103
|
+
3. Keep API compatibility unless current API is inherently inaccessible.
|
|
104
|
+
4. Update docs and tests in the same small PR when behavior changes.
|
|
105
|
+
5. Avoid cross-component refactors in accessibility fix PRs.
|
|
106
|
+
|
|
107
|
+
## Manual screen reader validation guidance
|
|
108
|
+
|
|
109
|
+
For each audited component, explicitly state whether manual SR validation is needed and why.
|
|
110
|
+
|
|
111
|
+
Recommended baseline matrix:
|
|
112
|
+
- VoiceOver + Safari (macOS)
|
|
113
|
+
- NVDA + Firefox (Windows)
|
|
114
|
+
- Optional: JAWS + Chrome for enterprise parity
|
|
115
|
+
|
|
116
|
+
Validate at minimum:
|
|
117
|
+
- role announcement
|
|
118
|
+
- name announcement
|
|
119
|
+
- state announcement
|
|
120
|
+
- focus order
|
|
121
|
+
- action feedback after interaction
|
|
122
|
+
|
|
123
|
+
## Example audit prompt (single component)
|
|
124
|
+
|
|
125
|
+
> Audit the `Link` component only using the Component Accessibility Audit Skill. Check semantic HTML, accessible names, keyboard behavior, focus management, ARIA/state handling, icon-only usage, contrast/token risks, tests, docs, and manual screen reader validation needs. Output findings using the required template and assign severity with blocker/high/medium/low. Do not implement fixes.
|
|
126
|
+
|
|
127
|
+
## Output expectations
|
|
128
|
+
|
|
129
|
+
- Be explicit and evidence-based.
|
|
130
|
+
- Distinguish verified findings from assumptions.
|
|
131
|
+
- Keep findings actionable for small follow-up PRs.
|
|
132
|
+
- If not verified, mark as "not verified".
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# UX Writing Coach
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Provide multilingual UX writing review for digital product copy.
|
|
6
|
+
|
|
7
|
+
This skill improves user-facing text for clarity, consistency, accessibility, usability, and tone-of-voice alignment.
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Use this skill when reviewing or rewriting:
|
|
12
|
+
- UI labels
|
|
13
|
+
- button text
|
|
14
|
+
- links and CTAs
|
|
15
|
+
- helper text
|
|
16
|
+
- validation and error messages
|
|
17
|
+
- empty states
|
|
18
|
+
- success and feedback messages
|
|
19
|
+
- transactional or task-supporting product copy
|
|
20
|
+
|
|
21
|
+
Default language is English. Core supported languages are English, German, and French.
|
|
22
|
+
|
|
23
|
+
## Language behaviour
|
|
24
|
+
|
|
25
|
+
- Start in English by default.
|
|
26
|
+
- If the user writes in German, respond in German.
|
|
27
|
+
- If the user writes in French, respond in French.
|
|
28
|
+
- If the user requests another language, adapt if possible.
|
|
29
|
+
- Preserve the language of the source text unless translation is explicitly requested.
|
|
30
|
+
|
|
31
|
+
## Working principles
|
|
32
|
+
|
|
33
|
+
- Be concise, practical, and supportive.
|
|
34
|
+
- Focus on the most relevant improvements first.
|
|
35
|
+
- Do not over-edit.
|
|
36
|
+
- Do not make text longer, more formal, or more complex unless it clearly improves usability.
|
|
37
|
+
- If the text is already strong, say so and suggest only meaningful refinements.
|
|
38
|
+
- Encourage the user to decide which suggestions to adopt.
|
|
39
|
+
|
|
40
|
+
## Review criteria
|
|
41
|
+
|
|
42
|
+
Check the text for:
|
|
43
|
+
- grammar
|
|
44
|
+
- spelling
|
|
45
|
+
- punctuation
|
|
46
|
+
- clarity
|
|
47
|
+
- consistency
|
|
48
|
+
- inclusivity
|
|
49
|
+
- accessibility
|
|
50
|
+
- formatting
|
|
51
|
+
- tone of voice
|
|
52
|
+
|
|
53
|
+
## UX writing principles
|
|
54
|
+
|
|
55
|
+
Prefer copy that is:
|
|
56
|
+
- clear
|
|
57
|
+
- concise
|
|
58
|
+
- consistent
|
|
59
|
+
- empathetic
|
|
60
|
+
- helpful
|
|
61
|
+
- action-oriented
|
|
62
|
+
- error-preventing
|
|
63
|
+
|
|
64
|
+
## Accessibility rules
|
|
65
|
+
|
|
66
|
+
- Use plain language.
|
|
67
|
+
- Avoid ambiguity and unnecessary jargon.
|
|
68
|
+
- Make links, buttons, and CTAs specific and understandable out of context.
|
|
69
|
+
- Ensure instructions, feedback, and next steps are easy to understand.
|
|
70
|
+
- Use inclusive language.
|
|
71
|
+
|
|
72
|
+
## Typographic and formatting conventions
|
|
73
|
+
|
|
74
|
+
- Distinguish between user-facing copy and technical or system-facing content.
|
|
75
|
+
- Use ISO 8601 for technical, structured, machine-readable, or cross-market content.
|
|
76
|
+
- ISO 8601 date format: YYYY-MM-DD
|
|
77
|
+
- ISO 8601 date-time format: YYYY-MM-DDTHH:mm
|
|
78
|
+
- Use localized date and time formats for user-facing UX copy when readability is more important.
|
|
79
|
+
- Use the 24-hour time format unless context clearly requires otherwise.
|
|
80
|
+
- Use leading zeros where appropriate.
|
|
81
|
+
- Use an en dash (–) for ranges.
|
|
82
|
+
- Never mix date systems inconsistently within the same output.
|
|
83
|
+
- For German copy, use standard German weekday and month abbreviations where needed.
|
|
84
|
+
|
|
85
|
+
## Tone of voice
|
|
86
|
+
|
|
87
|
+
Aim for copy that is:
|
|
88
|
+
- clear
|
|
89
|
+
- friendly
|
|
90
|
+
- confident
|
|
91
|
+
- helpful
|
|
92
|
+
- human
|
|
93
|
+
|
|
94
|
+
Avoid copy that feels robotic, overly formal, or unnecessarily promotional.
|
|
95
|
+
|
|
96
|
+
## Preferred response structure
|
|
97
|
+
|
|
98
|
+
1. Brief assessment
|
|
99
|
+
2. Key improvements
|
|
100
|
+
3. Suggested rewrite
|
|
101
|
+
4. Clean final copy
|
|
102
|
+
|
|
103
|
+
## Operating instructions
|
|
104
|
+
|
|
105
|
+
When given text to review:
|
|
106
|
+
1. Analyse the text carefully.
|
|
107
|
+
2. Identify the most important issues first.
|
|
108
|
+
3. Explain the issues briefly and clearly.
|
|
109
|
+
4. Suggest an improved version.
|
|
110
|
+
5. Provide a clean final version ready to copy.
|
|
111
|
+
|
|
112
|
+
## Prompt template
|
|
113
|
+
|
|
114
|
+
Use this prompt shape when applying the skill:
|
|
115
|
+
|
|
116
|
+
> Review the following text according to the rules above, accessibility standards, formatting conventions, and the tone of voice of tui.com: "[text to review]"
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Foundations
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Foundations docs describe the canonical token, naming, theming, parity, and
|
|
6
|
+
format rules that other layers build on.
|
|
7
|
+
|
|
8
|
+
## Canonical files
|
|
9
|
+
|
|
10
|
+
The detailed foundation ADRs are the source of truth:
|
|
11
|
+
|
|
12
|
+
| File | Topic |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `foundation-001-token-layering.md` | Core -> Color Modes -> Semantics -> Components token layering |
|
|
15
|
+
| `foundation-002-naming-and-grouping.md` | Token naming, grouping, and variant-first structure |
|
|
16
|
+
| `foundation-003-color-semantics-and-status.md` | Semantic color roles, status vs interaction state |
|
|
17
|
+
| `foundation-004-typography-scale-and-line-height.md` | Typography scale, line height, and role composition |
|
|
18
|
+
| `foundation-005-responsive-breakpoints-and-containers.md` | Breakpoints, container thresholds, and responsive separation |
|
|
19
|
+
| `foundation-006-z-index-layering.md` | Z-index tokenization and overlay layering |
|
|
20
|
+
| `foundation-007-typography-selectors-and-specificity.md` | Typography selectors, class API, and specificity rules |
|
|
21
|
+
| `foundation-008-mode-activation-and-consumer-control.md` | Light/dark mode scoping and consumer-owned activation |
|
|
22
|
+
| `foundation-009-component-boundaries-and-utility.md` | Standalone component boundary test and utility check |
|
|
23
|
+
| `foundation-010-implementation-and-pipeline-workflow.md` | Token-first implementation workflow and validation commands |
|
|
24
|
+
| `foundation-011-branching-and-release-governance.md` | Feature-branch, PR, and release governance |
|
|
25
|
+
| `foundation-012-minimal-markup-and-composition.md` | Minimal markup, composition, and wrapper discipline |
|
|
26
|
+
|
|
27
|
+
## Who should read this
|
|
28
|
+
|
|
29
|
+
- Designers defining token and naming decisions
|
|
30
|
+
- Engineers implementing or validating token-driven UI
|
|
31
|
+
- Agents doing token, component, or parity work
|
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Foundation-007 – Typography Selectors and Specificity
|
|
3
|
+
status: active
|
|
4
|
+
type: foundation-decision
|
|
5
|
+
---
|
|
6
|
+
|
|
1
7
|
# Foundation-007: Typography Selectors and Specificity
|
|
2
8
|
|
|
3
9
|
## Purpose
|
|
@@ -16,7 +22,7 @@ Provide a consistent typography API with low selector specificity and predictabl
|
|
|
16
22
|
|
|
17
23
|
4. Use `:where()` for zero-specificity size/scale selectors where possible.
|
|
18
24
|
|
|
19
|
-
5. Reserve data attributes (for example `[data-
|
|
25
|
+
5. Reserve data attributes (for example `[data-brand]`, `[data-mode]`, `[data-density]`) for context/state, not as primary styling API.
|
|
20
26
|
|
|
21
27
|
## Implications
|
|
22
28
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ui-foundations",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Token-first UI foundations with CSS, tokens, and React exports.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -29,26 +29,31 @@
|
|
|
29
29
|
"./react/input": "./dist/react/input.js",
|
|
30
30
|
"./react/label": "./dist/react/label.js",
|
|
31
31
|
"./assets/*": "./dist/assets/*",
|
|
32
|
-
"./tokens/core.css": "./dist/tokens/css/core-
|
|
33
|
-
"./tokens/primitives.css": "./dist/tokens/css/core-
|
|
34
|
-
"./tokens/brand-a.css": "./dist/tokens/css/themes-
|
|
35
|
-
"./tokens/brand-b.css": "./dist/tokens/css/themes-
|
|
36
|
-
"./tokens/
|
|
37
|
-
"./tokens/color
|
|
38
|
-
"./tokens/color-
|
|
39
|
-
"./tokens/
|
|
40
|
-
"./tokens/
|
|
32
|
+
"./tokens/core.css": "./dist/tokens/css/core-primitives.tokens.css",
|
|
33
|
+
"./tokens/primitives.css": "./dist/tokens/css/core-primitives.tokens.css",
|
|
34
|
+
"./tokens/brand-a.css": "./dist/tokens/css/themes-brands.tokens.brand-a.css",
|
|
35
|
+
"./tokens/brand-b.css": "./dist/tokens/css/themes-brands.tokens.brand-b.css",
|
|
36
|
+
"./tokens/brand-c.css": "./dist/tokens/css/themes-brands.tokens.brand-c.css",
|
|
37
|
+
"./tokens/color.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
|
|
38
|
+
"./tokens/color-light.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
|
|
39
|
+
"./tokens/color-dark.css": "./dist/tokens/css/appearance-modes.tokens.mode-dark.css",
|
|
40
|
+
"./tokens/semantic.css": "./dist/tokens/css/semantics-roles.tokens.css",
|
|
41
|
+
"./tokens/components.css": "./dist/tokens/css/components-ui.tokens.css",
|
|
42
|
+
"./macros/ui.njk": "./dist/macros/ui.njk"
|
|
41
43
|
},
|
|
42
44
|
"scripts": {
|
|
43
45
|
"icons:generate-list": "node scripts/generate-icon-list.mjs",
|
|
46
|
+
"plugin:meta": "node scripts/generate-plugin-meta.mjs",
|
|
44
47
|
"lint:js": "node scripts/lint-js.mjs",
|
|
45
48
|
"lint": "npm run lint:js",
|
|
46
49
|
"test:unit": "node --test tests/*.test.mjs",
|
|
47
50
|
"test": "npm run test:unit",
|
|
48
51
|
"smoke:check": "node scripts/smoke-check.mjs",
|
|
49
52
|
"assets:check": "node scripts/check-asset-refs.mjs",
|
|
53
|
+
"rules:validate": "node scripts/validate-rule-pipeline.mjs",
|
|
50
54
|
"tokens:generate": "node scripts/extract-tokens.js",
|
|
51
55
|
"tokens:validate": "node scripts/validate-tokens.mjs",
|
|
56
|
+
"dtcg:validate": "node scripts/validate-dtcg.mjs",
|
|
52
57
|
"tokens:build": "npm run tokens:generate",
|
|
53
58
|
"build:css": "node scripts/build-css.mjs",
|
|
54
59
|
"build:all": "npm run icons:generate-list && npm run tokens:generate && npm run build:css",
|
|
@@ -62,7 +67,7 @@
|
|
|
62
67
|
"release:publish": "npm publish",
|
|
63
68
|
"docs:build": "eleventy",
|
|
64
69
|
"docs:site": "npm run build:all && npm run docs:build",
|
|
65
|
-
"ci:check": "npm run lint && npm run test:unit && npm run build:all && npm run smoke:check && npm run tokens:validate && npm run assets:check && npm run docs:build",
|
|
70
|
+
"ci:check": "npm run lint && npm run test:unit && npm run build:all && npm run smoke:check && npm run tokens:validate && npm run dtcg:validate && npm run assets:check && npm run rules:validate && npm run docs:build",
|
|
66
71
|
"docs:dev": "npm run build:all && eleventy --serve"
|
|
67
72
|
},
|
|
68
73
|
"devDependencies": {
|
|
@@ -1,127 +0,0 @@
|
|
|
1
|
-
/* Auto-generated design tokens from Figma */
|
|
2
|
-
/* Generated on 2026-03-31T20:27:09.731Z */
|
|
3
|
-
|
|
4
|
-
:root {
|
|
5
|
-
--color-neutral-100: rgb(230 230 230);
|
|
6
|
-
--color-neutral-200: rgb(204 204 204);
|
|
7
|
-
--color-neutral-300: rgb(179 179 179);
|
|
8
|
-
--color-neutral-400: rgb(128 128 128);
|
|
9
|
-
--color-neutral-500: rgb(128 128 128);
|
|
10
|
-
--color-neutral-600: rgb(102 102 102);
|
|
11
|
-
--color-neutral-700: rgb(77 77 77);
|
|
12
|
-
--color-neutral-800: rgb(51 51 51);
|
|
13
|
-
--color-neutral-900: rgb(26 26 26);
|
|
14
|
-
--color-neutral-1000: rgb(0 0 0);
|
|
15
|
-
--color-neutral-alpha-100: rgba(0 0 0 / 0.1);
|
|
16
|
-
--color-neutral-alpha-200: rgba(0 0 0 / 0.2);
|
|
17
|
-
--color-neutral-alpha-300: rgba(0 0 0 / 0.3);
|
|
18
|
-
--color-neutral-alpha-400: rgba(0 0 0 / 0.4);
|
|
19
|
-
--color-neutral-alpha-500: rgba(0 0 0 / 0.5);
|
|
20
|
-
--color-neutral-alpha-600: rgba(0 0 0 / 0.6);
|
|
21
|
-
--color-neutral-alpha-700: rgba(0 0 0 / 0.7);
|
|
22
|
-
--color-neutral-alpha-800: rgba(0 0 0 / 0.8);
|
|
23
|
-
--color-neutral-alpha-900: rgba(0 0 0 / 0.9);
|
|
24
|
-
--color-neutral-alpha-000: rgba(0 0 0 / 0);
|
|
25
|
-
--color-neutral-000: rgb(255 255 255);
|
|
26
|
-
--color-brand-a-purple-200: rgb(222 192 255);
|
|
27
|
-
--color-brand-a-purple-600: rgb(151 71 255);
|
|
28
|
-
--color-brand-a-purple-800: rgb(85 26 139);
|
|
29
|
-
--color-brand-a-blue-200: rgb(226 244 253);
|
|
30
|
-
--color-brand-a-blue-500: rgb(112 203 244);
|
|
31
|
-
--color-brand-a-blue-700: rgb(12 75 243);
|
|
32
|
-
--color-brand-a-blue-800: rgb(27 17 92);
|
|
33
|
-
--color-brand-a-green: rgb(19 174 92);
|
|
34
|
-
--color-brand-a-red: rgb(255 0 0);
|
|
35
|
-
--color-brand-b-purple-200: rgb(196 143 255);
|
|
36
|
-
--color-brand-b-purple-600: rgb(122 20 255);
|
|
37
|
-
--color-brand-b-purple-800: rgb(58 18 95);
|
|
38
|
-
--color-brand-b-blue-200: rgb(179 226 250);
|
|
39
|
-
--color-brand-b-blue-500: rgb(66 186 240);
|
|
40
|
-
--color-brand-b-blue-700: rgb(10 60 194);
|
|
41
|
-
--color-brand-b-blue-800: rgb(14 9 47);
|
|
42
|
-
--color-brand-b-red: rgb(204 0 0);
|
|
43
|
-
--color-brand-b-green: rgb(14 129 68);
|
|
44
|
-
--color-transparent: rgba(0 0 0 / 0);
|
|
45
|
-
--font-size-md: 1rem;
|
|
46
|
-
--font-size-xs: .75rem;
|
|
47
|
-
--font-size-sm: .875rem;
|
|
48
|
-
--font-size-lg: 1.25rem;
|
|
49
|
-
--font-size-xl: 1.5rem;
|
|
50
|
-
--font-size-xxl: 2rem;
|
|
51
|
-
--font-size-xxxl: 2.5rem;
|
|
52
|
-
--font-weight-100: 100;
|
|
53
|
-
--font-weight-200: 200;
|
|
54
|
-
--font-weight-300: 300;
|
|
55
|
-
--font-weight-400: 400;
|
|
56
|
-
--font-weight-500: 500;
|
|
57
|
-
--font-weight-600: 600;
|
|
58
|
-
--font-weight-700: 700;
|
|
59
|
-
--font-weight-800: 800;
|
|
60
|
-
--font-weight-900: 900;
|
|
61
|
-
--font-family-sans: Inter;
|
|
62
|
-
--font-family-serif: Rokkitt;
|
|
63
|
-
--font-family-mono: SFMono-Regular;
|
|
64
|
-
--line-height-xs: 1rem;
|
|
65
|
-
--line-height-sm: 1.25rem;
|
|
66
|
-
--line-height-md: 1.5rem;
|
|
67
|
-
--line-height-lg: 1.75rem;
|
|
68
|
-
--line-height-xl: 2rem;
|
|
69
|
-
--line-height-xxl: 2.75rem;
|
|
70
|
-
--line-height-xxxl: 3.5rem;
|
|
71
|
-
--size-spacing-100: .25rem;
|
|
72
|
-
--size-spacing-200: .5rem;
|
|
73
|
-
--size-spacing-300: .75rem;
|
|
74
|
-
--size-spacing-400: 1rem;
|
|
75
|
-
--size-spacing-500: 1.25rem;
|
|
76
|
-
--size-spacing-600: 1.5rem;
|
|
77
|
-
--size-spacing-700: 2rem;
|
|
78
|
-
--size-spacing-800: 2.5rem;
|
|
79
|
-
--size-spacing-900: 3rem;
|
|
80
|
-
--size-spacing-1000: 4rem;
|
|
81
|
-
--size-spacing-000: 0;
|
|
82
|
-
--size-radius-100: .125rem;
|
|
83
|
-
--size-radius-200: .25rem;
|
|
84
|
-
--size-radius-300: .375rem;
|
|
85
|
-
--size-radius-400: .5rem;
|
|
86
|
-
--size-radius-500: .75rem;
|
|
87
|
-
--size-radius-600: 1rem;
|
|
88
|
-
--size-radius-700: 1.25rem;
|
|
89
|
-
--size-radius-800: 1.5rem;
|
|
90
|
-
--size-radius-900: 2rem;
|
|
91
|
-
--size-radius-000: 0;
|
|
92
|
-
--size-radius-full: 625rem;
|
|
93
|
-
--shadow-focus: .5rem;
|
|
94
|
-
--breakpoint-100: 580px;
|
|
95
|
-
--breakpoint-200: 760px;
|
|
96
|
-
--breakpoint-300: 960px;
|
|
97
|
-
--breakpoint-400: 1200px;
|
|
98
|
-
--breakpoint-500: 1440px;
|
|
99
|
-
--breakpoint-600: 1920px;
|
|
100
|
-
--container-100: 192px;
|
|
101
|
-
--container-200: 384px;
|
|
102
|
-
--container-300: 576px;
|
|
103
|
-
--container-400: 768px;
|
|
104
|
-
--container-500: 960px;
|
|
105
|
-
--container-600: 1152px;
|
|
106
|
-
--size-border-100: .0625rem;
|
|
107
|
-
--size-border-200: .125rem;
|
|
108
|
-
--size-border-300: .1875rem;
|
|
109
|
-
--size-border-000: 0;
|
|
110
|
-
--layout-columns: 12;
|
|
111
|
-
--layout-gutter: 1rem;
|
|
112
|
-
--layout-max-width: 1236px;
|
|
113
|
-
--layout-column-max-width: 412px;
|
|
114
|
-
--layout-float-breakpoint: 1220px;
|
|
115
|
-
--layout-base-grid: .25rem;
|
|
116
|
-
--zindex-fixed: 1030;
|
|
117
|
-
--zindex-sticky: 1020;
|
|
118
|
-
--zindex-dropdown: 1000;
|
|
119
|
-
--zindex-dropdown-base: 900;
|
|
120
|
-
--zindex-modal: 1050;
|
|
121
|
-
--zindex-base: 0;
|
|
122
|
-
--zindex-tooltip: 1070;
|
|
123
|
-
--zindex-raised: 1;
|
|
124
|
-
--zindex-popover: 1060;
|
|
125
|
-
--zindex-modal-overlay: 1040;
|
|
126
|
-
--zindex-hidden: -1;
|
|
127
|
-
}
|