ui-foundations 0.4.1 → 0.7.0

package/dist/ui/patterns/checkbox.css

@@ -7,12 +7,12 @@
     font-weight: var(--typography-label-font-weight);
     font-size: var(--typography-label-font-size);
     line-height: var(--typography-label-line-height);
-    color: var(--input-checkbox-text-color-default);
+    color: var(--checkbox-text-color-default);
     cursor: pointer;
   }
 
   .checkbox-field.is-disabled {
-    color: var(--input-checkbox-text-color-disabled);
+    color: var(--checkbox-text-color-disabled);
     cursor: not-allowed;
   }
 
@@ -25,10 +25,10 @@
     place-content: center;
     border-style: solid;
     border-width: var(--checkbox-border-size-default);
-    border-color: var(--input-checkbox-border-color-default);
+    border-color: var(--checkbox-border-color-default);
     border-radius: var(--corner-checkbox-radius);
-    background: var(--input-checkbox-container-background-default);
-    color: var(--input-checkbox-text-color-active);
+    background: var(--checkbox-container-background-default);
+    color: var(--checkbox-text-color-active);
     cursor: pointer;
   }
 
@@ -39,8 +39,8 @@
 
   .checkbox:checked,
   .checkbox.is-checked {
-    border-color: var(--input-checkbox-border-color-active);
-    background: var(--input-checkbox-container-background-active);
+    border-color: var(--checkbox-border-color-active);
+    background: var(--checkbox-container-background-active);
   }
 
   .checkbox:checked::after,
@@ -61,8 +61,8 @@
 
   .checkbox:indeterminate,
   .checkbox.is-indeterminate {
-    border-color: var(--input-checkbox-border-color-active);
-    background: var(--input-checkbox-container-background-active);
+    border-color: var(--checkbox-border-color-active);
+    background: var(--checkbox-container-background-active);
   }
 
   .checkbox:indeterminate::after,
@@ -77,9 +77,9 @@
   .checkbox.is-hover {
     background:
       linear-gradient(0deg, var(--color-overlay-hover), var(--color-overlay-hover)),
-      var(--input-checkbox-container-background-hover);
-    color: var(--input-checkbox-text-color-hover);
-    border-color: var(--input-checkbox-border-color-hover);
+      var(--checkbox-container-background-hover);
+    color: var(--checkbox-text-color-hover);
+    border-color: var(--checkbox-border-color-hover);
     border-width: var(--checkbox-border-size-hover);
   }
 
@@ -87,9 +87,9 @@
   .checkbox.is-checked.is-hover {
     background:
       linear-gradient(0deg, var(--color-overlay-hover), var(--color-overlay-hover)),
-      var(--input-checkbox-container-background-active);
-    color: var(--input-checkbox-text-color-hover);
-    border-color: var(--input-checkbox-border-color-hover);
+      var(--checkbox-container-background-active);
+    color: var(--checkbox-text-color-hover);
+    border-color: var(--checkbox-border-color-hover);
     border-width: var(--checkbox-border-size-hover);
   }
 
@@ -97,9 +97,9 @@
   .checkbox.is-indeterminate.is-hover {
     background:
       linear-gradient(0deg, var(--color-overlay-hover), var(--color-overlay-hover)),
-      var(--input-checkbox-container-background-active);
-    color: var(--input-checkbox-text-color-hover);
-    border-color: var(--input-checkbox-border-color-hover);
+      var(--checkbox-container-background-active);
+    color: var(--checkbox-text-color-hover);
+    border-color: var(--checkbox-border-color-hover);
     border-width: var(--checkbox-border-size-hover);
   }
 
@@ -107,8 +107,8 @@
   .checkbox.is-active {
     background:
       linear-gradient(0deg, var(--color-overlay-active), var(--color-overlay-active)),
-      var(--input-checkbox-container-background-default);
-    border-color: var(--input-checkbox-border-color-active);
+      var(--checkbox-container-background-default);
+    border-color: var(--checkbox-border-color-active);
     border-width: var(--size-border-200);
   }
 
@@ -116,21 +116,21 @@
   .checkbox.is-checked.is-active {
     background:
       linear-gradient(0deg, var(--color-overlay-active), var(--color-overlay-active)),
-      var(--input-checkbox-container-background-active);
-    border-color: var(--input-checkbox-border-color-active);
+      var(--checkbox-container-background-active);
+    border-color: var(--checkbox-border-color-active);
   }
 
   .checkbox:indeterminate:active,
   .checkbox.is-indeterminate.is-active {
     background:
       linear-gradient(0deg, var(--color-overlay-active), var(--color-overlay-active)),
-      var(--input-checkbox-container-background-active);
-    border-color: var(--input-checkbox-border-color-active);
+      var(--checkbox-container-background-active);
+    border-color: var(--checkbox-border-color-active);
   }
 
   .checkbox:focus-visible,
   .checkbox.is-focus-visible {
-    border-color: var(--input-checkbox-border-color-focus);
+    border-color: var(--checkbox-border-color-focus);
     outline: none;
     box-shadow: 0 0 0 var(--shadow-focus, 0) var(--color-focus, transparent);
   }
@@ -138,9 +138,9 @@
   .checkbox:disabled,
   .checkbox.is-disabled {
     border-width: var(--checkbox-border-size-disabled);
-    border-color: var(--input-checkbox-border-color-disabled);
-    background: var(--input-checkbox-container-background-disabled);
-    color: var(--input-checkbox-text-color-disabled);
+    border-color: var(--checkbox-border-color-disabled);
+    background: var(--checkbox-container-background-disabled);
+    color: var(--checkbox-text-color-disabled);
     cursor: not-allowed;
   }
 }

package/dist/ui/patterns/divider.css

@@ -0,0 +1,25 @@
+@layer components {
+  .divider {
+    border: none;
+    margin: 0;
+    padding: 0;
+    background: var(--divider-color, var(--color-border-default));
+    block-size: var(--size-border-100);
+    inline-size: 100%;
+    align-self: stretch;
+  }
+
+  /* ── Vertical orientation ── */
+
+  .divider[aria-orientation="vertical"] {
+    block-size: auto;
+    inline-size: var(--size-border-100);
+    align-self: stretch;
+  }
+
+  /* ── Subtle variant ── */
+
+  .divider.subtle {
+    --divider-color: var(--color-border-subtle);
+  }
+}

package/dist/ui/patterns/form.css

@@ -0,0 +1,112 @@
+@layer components {
+  /* ----------------------------------------------------------------
+   * Form — layout container for form fields
+   * ---------------------------------------------------------------- */
+
+  .form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--form-gap);
+    padding-inline: var(--form-padding-inline);
+    padding-block: var(--form-padding-block);
+    background: var(--form-container-background);
+    border: var(--form-border-size) solid var(--form-container-border-color);
+    border-radius: var(--form-border-radius);
+  }
+
+  .form.borderless {
+    border: none;
+    padding: 0;
+    background: transparent;
+  }
+
+  /* ----------------------------------------------------------------
+   * Form Group — groups related fields with an optional title
+   * ---------------------------------------------------------------- */
+
+  .form-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--form-group-gap);
+    margin: 0;
+    padding: 0;
+    border: 0;
+    min-inline-size: 0;
+  }
+
+  .form-group__title {
+    font-family: var(--typography-heading-font-family);
+    font-weight: var(--typography-heading-font-weight);
+    font-size: var(--typography-heading-font-size-sm);
+    line-height: var(--typography-heading-line-height-sm);
+    color: var(--form-group-title-color);
+    margin: 0;
+  }
+
+  /* ----------------------------------------------------------------
+   * Form Field — single field with label, input, and helper/error
+   * ---------------------------------------------------------------- */
+
+  .form-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--form-field-gap);
+  }
+
+  .form-field[data-label-position="side"] {
+    flex-direction: row;
+    align-items: flex-start;
+  }
+
+  .form-field[data-label-position="side"] > .field-label {
+    flex-shrink: 0;
+    inline-size: 8rem;
+    padding-block-start: var(--size-spacing-200);
+  }
+
+  .form-field[data-label-position="side"] > .form-field__body {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--form-field-gap);
+  }
+
+  /* ----------------------------------------------------------------
+   * Helper and error text
+   * ---------------------------------------------------------------- */
+
+  .form-field__helper {
+    font-family: var(--typography-body-font-family);
+    font-size: var(--font-size-sm);
+    line-height: var(--line-height-sm);
+    color: var(--form-field-helper-text-color-default);
+    margin: 0;
+  }
+
+  .form-field.is-invalid .form-field__helper {
+    color: var(--form-field-helper-text-color-invalid);
+  }
+
+  /* ----------------------------------------------------------------
+   * Form Actions — button area at the bottom
+   * ---------------------------------------------------------------- */
+
+  .form-actions {
+    display: flex;
+    gap: var(--size-spacing-200);
+    justify-content: flex-end;
+    padding-block-start: var(--size-spacing-200);
+  }
+
+  .form-actions[data-align="start"] {
+    justify-content: flex-start;
+  }
+
+  .form-actions[data-align="stretch"] {
+    flex-direction: column;
+  }
+
+  .form-actions[data-align="stretch"] > * {
+    inline-size: 100%;
+  }
+}

package/dist/ui/patterns/input.css

@@ -7,25 +7,25 @@
     font-weight: var(--input-font-weight);
     font-size: var(--input-font-size);
     line-height: var(--input-line-height, var(--button-line-height, 1.5));
-    color: var(--input-text-text-color-default);
-    background: var(--input-text-container-background-default);
+    color: var(--input-text-color-default);
+    background: var(--input-container-background-default);
     border-style: solid;
     border-width: var(--input-border-size-default);
-    border-color: var(--input-text-border-color-default);
+    border-color: var(--input-border-color-default);
     border-radius: var(--input-border-radius);
     padding-inline: var(--input-padding-inline);
     padding-block: var(--input-padding-block);
   }
 
   .input::placeholder {
-    color: var(--input-text-text-color-placeholder);
+    color: var(--input-text-color-placeholder);
   }
 
   .input:hover,
   .input.is-hover {
     background:
       linear-gradient(0deg, var(--input-overlay-hover), var(--input-overlay-hover)),
-      var(--input-text-container-background-default);
+      var(--input-container-background-default);
     border-width: var(--input-border-size-hover);
     padding-inline: calc(
       var(--input-padding-inline) + var(--input-border-size-default) -
@@ -35,15 +35,15 @@
       var(--input-padding-block) + var(--input-border-size-default) -
         var(--input-border-size-hover)
     );
-    border-color: var(--input-text-border-color-hover);
-    color: var(--input-text-text-color-hover);
+    border-color: var(--input-border-color-hover);
+    color: var(--input-text-color-hover);
   }
 
   .input:active,
   .input.is-active {
     background:
       linear-gradient(0deg, var(--input-overlay-active), var(--input-overlay-active)),
-      var(--input-text-container-background-default);
+      var(--input-container-background-default);
     border-width: var(--input-border-size-active);
     padding-inline: calc(
       var(--input-padding-inline) + var(--input-border-size-default) -
@@ -53,14 +53,14 @@
       var(--input-padding-block) + var(--input-border-size-default) -
         var(--input-border-size-active)
     );
-    border-color: var(--input-text-border-color-active);
-    color: var(--input-text-text-color-active);
+    border-color: var(--input-border-color-active);
+    color: var(--input-text-color-active);
   }
 
   .input:focus-visible,
   .input.is-focus-visible {
-    background: var(--input-text-container-background-focus);
-    border-color: var(--input-text-border-color-focus);
+    background: var(--input-container-background-focus);
+    border-color: var(--input-border-color-focus);
     outline: none;
     box-shadow: 0 0 0 var(--shadow-focus, 0) var(--color-focus, transparent);
   }

package/dist/ui/patterns/label.css

@@ -2,7 +2,7 @@
   .label-content {
     display: inline-flex;
     align-items: center;
-    gap: var(--label-gap, 0.5em);
+    gap: var(--typography-label-gap, 0.5em);
     line-height: inherit;
   }
 

package/dist/ui/patterns/tabs.css

@@ -0,0 +1,71 @@
+@layer components {
+  .tabs {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .tab-list {
+    display: flex;
+    gap: 0;
+    border-block-end: var(--size-border-100) solid var(--color-border-default);
+  }
+
+  .tab-list[aria-orientation="vertical"] {
+    flex-direction: column;
+    border-block-end: none;
+    border-inline-end: var(--size-border-100) solid var(--color-border-default);
+  }
+
+  .tab {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding-inline: var(--size-spacing-400);
+    padding-block: var(--size-spacing-300);
+    font-family: var(--font-family-sans);
+    font-size: var(--font-size-md);
+    font-weight: var(--font-weight-500);
+    line-height: var(--line-height-md);
+    color: var(--color-text-default);
+    background: transparent;
+    border: none;
+    border-block-end: var(--size-border-200) solid transparent;
+    cursor: pointer;
+    white-space: nowrap;
+    transition: border-color 0.15s ease, color 0.15s ease;
+  }
+
+  .tab:hover,
+  .tab.is-hover {
+    color: var(--color-text-brand);
+    border-block-end-color: var(--color-border-subtle);
+  }
+
+  .tab[aria-selected="true"],
+  .tab.is-selected {
+    color: var(--color-text-brand);
+    font-weight: var(--font-weight-600);
+    border-block-end-color: var(--color-border-brand);
+  }
+
+  .tab:focus-visible,
+  .tab.is-focus-visible {
+    outline: none;
+    box-shadow: inset 0 0 0 var(--shadow-focus) var(--color-focus);
+  }
+
+  .tab:disabled,
+  .tab.is-disabled {
+    color: var(--color-text-disabled);
+    cursor: not-allowed;
+    border-block-end-color: transparent;
+  }
+
+  .tab-panel {
+    padding-block: var(--size-spacing-400);
+  }
+
+  .tab-panel[hidden] {
+    display: none;
+  }
+}

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