ui-foundations 0.4.1 → 0.6.0

package/dist/ui/patterns/textarea.css

@@ -0,0 +1,50 @@
+@layer components {
+  .textarea {
+    display: block;
+    inline-size: 100%;
+    min-block-size: calc(var(--line-height-md) * 3 + var(--size-spacing-300) * 2);
+    padding-inline: var(--size-spacing-300);
+    padding-block: var(--size-spacing-300);
+    font-family: var(--font-family-sans);
+    font-size: var(--font-size-md);
+    line-height: var(--line-height-md);
+    color: var(--color-text-default);
+    background: var(--color-fill-surface);
+    border: var(--size-border-100) solid var(--color-border-default);
+    border-radius: var(--size-radius-300);
+    resize: vertical;
+    transition: border-color 0.15s ease;
+  }
+
+  .textarea::placeholder {
+    color: var(--color-text-disabled);
+  }
+
+  .textarea:hover,
+  .textarea.is-hover {
+    border-color: var(--color-border-strong);
+  }
+
+  .textarea:focus-visible,
+  .textarea.is-focus-visible {
+    border-color: var(--color-focus);
+    outline: none;
+    box-shadow: 0 0 0 var(--shadow-focus) var(--color-focus);
+  }
+
+  .textarea:disabled,
+  .textarea.is-disabled {
+    color: var(--color-text-disabled);
+    background: var(--color-fill-disabled);
+    border-color: var(--color-border-disabled);
+    cursor: not-allowed;
+    resize: none;
+  }
+
+  .textarea[readonly] {
+    background: var(--color-fill-surface);
+    border-color: var(--color-border-default);
+    cursor: default;
+    resize: none;
+  }
+}

package/dist/ui/patterns/tooltip.css

@@ -0,0 +1,64 @@
+@layer components {
+  .tooltip {
+    position: absolute;
+    z-index: var(--zindex-tooltip);
+    max-inline-size: 15rem;
+    padding-inline: var(--size-spacing-300);
+    padding-block: var(--size-spacing-200);
+    font-family: var(--font-family-sans);
+    font-size: var(--font-size-sm);
+    line-height: var(--line-height-sm);
+    color: var(--color-text-inverse);
+    background: var(--color-neutral-900);
+    border-radius: var(--size-radius-300);
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.15s ease;
+  }
+
+  .tooltip.is-visible {
+    opacity: 1;
+  }
+
+  /* ── Placement ── */
+
+  .tooltip[data-placement="top"] {
+    inset-block-end: 100%;
+    inset-inline-start: 50%;
+    transform: translateX(-50%);
+    margin-block-end: var(--size-spacing-200);
+  }
+
+  .tooltip[data-placement="bottom"] {
+    inset-block-start: 100%;
+    inset-inline-start: 50%;
+    transform: translateX(-50%);
+    margin-block-start: var(--size-spacing-200);
+  }
+
+  .tooltip[data-placement="left"] {
+    inset-inline-end: 100%;
+    inset-block-start: 50%;
+    transform: translateY(-50%);
+    margin-inline-end: var(--size-spacing-200);
+  }
+
+  .tooltip[data-placement="right"] {
+    inset-inline-start: 100%;
+    inset-block-start: 50%;
+    transform: translateY(-50%);
+    margin-inline-start: var(--size-spacing-200);
+  }
+
+  /* ── Trigger wrapper ── */
+
+  .tooltip-trigger {
+    position: relative;
+    display: inline-flex;
+  }
+
+  .tooltip-trigger:hover > .tooltip,
+  .tooltip-trigger:focus-within > .tooltip {
+    opacity: 1;
+  }
+}

package/docs/agentic/README.md

@@ -32,3 +32,4 @@ in the repository.
 ## Skills
 
 - `skills/ux-writing-coach.md` — multilingual UX writing review skill for product copy
+- `skills/component-accessibility-audit.md` — repeatable workflow and template for single-component accessibility audits

package/docs/agentic/skills/component-accessibility-audit.md

@@ -0,0 +1,132 @@
+# Component Accessibility Audit Skill
+
+## Purpose
+
+Create a repeatable, component-level accessibility audit workflow before implementation fixes.
+
+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.
+
+## Governance references (must read first)
+
+1. `DESIGN.md`
+2. `AGENTS.md`
+3. `docs/playbook.md`
+4. `docs/working-context.md`
+5. `docs/ui-foundations-rules.md`
+6. `docs/foundations/`
+7. `docs/agentic/assistant-behavior-rules.md`
+8. `IMPLEMENTATION.md`
+
+Never contradict these sources. Prefer explicit, verifiable findings over assumptions.
+
+## Scope
+
+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).
+
+Do not use this skill to implement broad fixes in the same PR. This skill is audit-first.
+
+## Audit workflow (repeatable)
+
+1. **Plan**
+   - Select exactly one component target.
+   - Confirm component surfaces in scope (CSS pattern, macro/template, React wrapper, docs, tests).
+
+2. **Collect evidence**
+   - Inspect source implementation files.
+   - Inspect usage examples and docs.
+   - Inspect test coverage.
+   - Record exact file paths and relevant lines.
+
+3. **Run checks**
+   - Semantic HTML
+   - Accessible names
+   - Keyboard behavior
+   - Focus management
+   - ARIA/state handling
+   - Form association (where relevant)
+   - Icon-only usage
+   - Contrast/token risks
+   - Test coverage
+   - Documentation gaps
+   - Manual screen reader validation needs
+
+4. **Score severity**
+   - Assign one severity per finding using the model below.
+
+5. **Propose minimal fix**
+   - Suggest the smallest safe change that resolves the finding.
+   - Keep fixes scoped to one component per follow-up PR.
+
+6. **Report**
+   - Output findings using the template in this document.
+
+## Severity model
+
+Use one of these labels:
+
+- **blocker**
+  - Breaks core accessibility behavior (e.g., no accessible name, unusable keyboard path, broken form semantics, missing focus trap in modal).
+  - Should be fixed before release.
+
+- **high**
+  - Major accessibility risk with likely user impact, but possible workaround exists.
+  - Prioritize immediately after blockers.
+
+- **medium**
+  - Important gap or drift that reduces accessibility quality/reliability.
+  - Schedule in near-term follow-up.
+
+- **low**
+  - Minor issue, documentation gap, or optimization with limited immediate impact.
+  - Track and resolve in routine improvements.
+
+## Findings template
+
+Use this exact structure for each finding:
+
+- **Component:**
+- **Check area:** (semantic HTML / accessible name / keyboard / focus / ARIA-state / form association / icon-only / contrast-token / tests / docs / manual SR)
+- **Observed behavior:**
+- **Expected behavior:**
+- **Evidence:** (file paths + line refs)
+- **Severity:** blocker | high | medium | low
+- **Minimal fix strategy:**
+- **Follow-up test need:**
+- **Manual SR validation need:**
+
+## Minimal-fix strategy
+
+When proposing a fix:
+
+1. Prefer native semantics over custom ARIA.
+2. Change the smallest surface that safely resolves the issue.
+3. Keep API compatibility unless current API is inherently inaccessible.
+4. Update docs and tests in the same small PR when behavior changes.
+5. Avoid cross-component refactors in accessibility fix PRs.
+
+## Manual screen reader validation guidance
+
+For each audited component, explicitly state whether manual SR validation is needed and why.
+
+Recommended baseline matrix:
+- VoiceOver + Safari (macOS)
+- NVDA + Firefox (Windows)
+- Optional: JAWS + Chrome for enterprise parity
+
+Validate at minimum:
+- role announcement
+- name announcement
+- state announcement
+- focus order
+- action feedback after interaction
+
+## Example audit prompt (single component)
+
+> 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.
+
+## Output expectations
+
+- Be explicit and evidence-based.
+- Distinguish verified findings from assumptions.
+- Keep findings actionable for small follow-up PRs.
+- If not verified, mark as "not verified".

package/docs/foundations/foundation-007-typography-selectors-and-specificity.md

@@ -22,7 +22,7 @@ Provide a consistent typography API with low selector specificity and predictabl
 
 4. Use `:where()` for zero-specificity size/scale selectors where possible.
 
-5. Reserve data attributes (for example `[data-theme]`, `[data-density]`) for context/state, not as primary styling API.
+5. Reserve data attributes (for example `[data-brand]`, `[data-mode]`, `[data-density]`) for context/state, not as primary styling API.
 
 ## Implications
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-foundations",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Token-first UI foundations with CSS, tokens, and React exports.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "./tokens/primitives.css": "./dist/tokens/css/core-primitives.tokens.css",
     "./tokens/brand-a.css": "./dist/tokens/css/themes-brands.tokens.brand-a.css",
     "./tokens/brand-b.css": "./dist/tokens/css/themes-brands.tokens.brand-b.css",
+    "./tokens/brand-c.css": "./dist/tokens/css/themes-brands.tokens.brand-c.css",
     "./tokens/color.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
     "./tokens/color-light.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
     "./tokens/color-dark.css": "./dist/tokens/css/appearance-modes.tokens.mode-dark.css",

package/dist/tokens/missing-tokens.json

@@ -1,43 +0,0 @@
-{
-  "generated": "2026-04-19T14:37:39.153Z",
-  "description": "Missing alias targets — these tokens are referenced but do not exist in any Figma export. Create them in Figma or add temporary mocks.",
-  "missing": [
-    {
-      "ref": "Size/Spacing/50",
-      "referencedBy": [
-        "Form/Slider/Track Height",
-        "Form/Slider/Track Height"
-      ],
-      "suggestedMock": {
-        "type": "number",
-        "value": 2,
-        "unit": "px",
-        "note": "Core: spacing 50 — add to Core (Primitives)"
-      }
-    },
-    {
-      "ref": "Color/Fill/Muted",
-      "referencedBy": [
-        "Form/Slider/Track Color",
-        "Form/Slider/Track Color"
-      ],
-      "suggestedMock": {
-        "type": "color",
-        "value": "#e5e5e5",
-        "note": "Semantic: muted fill — add to Appearance (Modes)"
-      }
-    },
-    {
-      "ref": "Color/Border/Focus",
-      "referencedBy": [
-        "Form/Slider/Focus Ring Color",
-        "Form/Slider/Focus Ring Color"
-      ],
-      "suggestedMock": {
-        "type": "color",
-        "value": "#3b82f6",
-        "note": "Semantic: focus border — add to Appearance (Modes)"
-      }
-    }
-  ]
-}