ui-foundations 0.1.0

package/dist/ui/patterns/button.css

@@ -0,0 +1,241 @@
+@layer components {
+  /* Button token usage examples (ui-foundations) */
+
+  .button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    white-space: nowrap;
+    background: var(--button-solid-container-background-default);
+    border-color: var(--button-solid-border-color-default);
+    border-width: var(--button-solid-border-size);
+    border-style: solid;
+    color: var(--button-solid-text-color-default);
+    border-radius: var(--button-border-radius);
+    padding-inline: var(--button-padding-inline);
+    padding-block: var(--button-padding-block);
+    cursor: pointer;
+    -webkit-text-fill-color: currentColor;
+  }
+
+  .button .label-content {
+    line-height: inherit;
+    color: inherit;
+    -webkit-text-fill-color: currentColor;
+  }
+
+  .button .label-content__text,
+  .button .icon {
+    color: inherit;
+    -webkit-text-fill-color: currentColor;
+  }
+
+  .button.button--icon-only {
+    padding-inline: var(--button-padding-block);
+  }
+
+  .button:hover,
+  .button.is-hover {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-hover),
+        var(--button-overlay-hover)
+      ),
+      var(--button-solid-container-background-default);
+    border-color: var(--button-solid-border-color-hover);
+    color: var(--button-solid-text-color-hover);
+  }
+
+  .button:active,
+  .button.is-active {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-active),
+        var(--button-overlay-active)
+      ),
+      var(--button-solid-container-background-default);
+    border-color: var(--button-solid-border-color-active);
+    color: var(--button-solid-text-color-active);
+  }
+
+  .button:focus-visible,
+  .button.is-focus-visible {
+    background: var(--button-solid-container-background-focus);
+    border-color: var(--button-solid-border-color-focus);
+    color: var(--button-solid-text-color-default);
+  }
+
+  .button.outline {
+    background: var(--button-outline-container-background-default);
+    border-color: var(--button-outline-border-color-default);
+    border-width: var(--button-outline-border-size);
+    border-style: solid;
+    color: var(--button-outline-text-color-default);
+  }
+
+  .button.outline:hover,
+  .button.outline.is-hover {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-hover),
+        var(--button-overlay-hover)
+      ),
+      var(--button-outline-container-background-default);
+    border-color: var(--button-outline-border-color-hover);
+    color: var(--button-outline-text-color-default);
+  }
+
+  .button.outline:active,
+  .button.outline.is-active {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-active),
+        var(--button-overlay-active)
+      ),
+      var(--button-outline-container-background-default);
+    border-color: var(--button-outline-border-color-active);
+    color: var(--button-outline-text-color-active);
+  }
+
+  .button.outline:focus-visible,
+  .button.outline.is-focus-visible {
+    background: var(--button-outline-container-background-focus);
+    border-color: var(--button-outline-border-color-focus);
+    color: var(--button-outline-text-color-default);
+  }
+
+  .button.ghost {
+    background: var(--button-ghost-container-background-default);
+    border-color: var(--button-ghost-border-color-default);
+    border-width: var(--button-ghost-border-size);
+    border-style: solid;
+    color: var(--button-ghost-text-color-default);
+  }
+
+  .button.ghost:hover,
+  .button.ghost.is-hover {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-hover),
+        var(--button-overlay-hover)
+      ),
+      var(--button-ghost-container-background-default);
+    border-color: var(--button-ghost-border-color-hover);
+    color: var(--button-ghost-text-color-default);
+  }
+
+  .button.ghost:active,
+  .button.ghost.is-active {
+    background: linear-gradient(
+        0deg,
+        var(--button-overlay-active),
+        var(--button-overlay-active)
+      ),
+      var(--button-ghost-container-background-default);
+    border-color: var(--button-ghost-border-color-active);
+    color: var(--button-ghost-text-color-active);
+  }
+
+  .button.ghost:focus-visible,
+  .button.ghost.is-focus-visible {
+    background: var(--button-ghost-container-background-focus);
+    border-color: var(--button-ghost-border-color-focus);
+    color: var(--button-ghost-text-color-default);
+  }
+
+  .button:disabled,
+  .button[disabled] {
+    cursor: not-allowed;
+    opacity: 0.6;
+    background: var(--button-container-background-disabled);
+    border-color: var(--button-border-color-disabled);
+    color: var(--button-text-color-disabled);
+  }
+
+  .button-group {
+    display: inline-flex;
+    align-items: stretch;
+    gap: var(--button-group-gap, var(--size-spacing-100, 0.25rem));
+  }
+
+  .button-group[data-orientation="vertical"] {
+    flex-direction: column;
+  }
+
+  .button-group[data-justify="stretch"] {
+    inline-size: 100%;
+  }
+
+  .button-group[data-justify="stretch"] > .button {
+    flex: 1 1 auto;
+    justify-content: center;
+  }
+
+  .button-group[data-attached="true"] {
+    gap: 0;
+  }
+
+  .button-group[data-attached="true"] > .button {
+    border-radius: 0;
+  }
+
+  .button-group[data-attached="true"]:not([data-orientation="vertical"])
+    > .button
+    + .button {
+    border-inline-start-width: 0;
+  }
+
+  .button-group[data-attached="true"][data-orientation="vertical"]
+    > .button
+    + .button {
+    border-block-start-width: 0;
+  }
+
+  .button-group[data-attached="true"]:not([data-orientation="vertical"])
+    > .button:first-child {
+    border-start-start-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+    border-end-start-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+  }
+
+  .button-group[data-attached="true"]:not([data-orientation="vertical"])
+    > .button:last-child {
+    border-start-end-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+    border-end-end-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+  }
+
+  .button-group[data-attached="true"][data-orientation="vertical"]
+    > .button:first-child {
+    border-start-start-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+    border-start-end-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+  }
+
+  .button-group[data-attached="true"][data-orientation="vertical"]
+    > .button:last-child {
+    border-end-start-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+    border-end-end-radius: var(
+      --button-group-border-radius,
+      var(--button-border-radius)
+    );
+  }
+}

package/dist/ui/patterns/checkbox.css

@@ -0,0 +1,97 @@
+@layer components {
+  .checkbox-field {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--typography-label-gap);
+    font-family: var(--typography-label-font-family);
+    font-weight: var(--typography-label-font-weight);
+    font-size: var(--typography-label-font-size);
+    line-height: var(--typography-label-line-height);
+    color: var(--color-text-default);
+    cursor: pointer;
+  }
+
+  .checkbox-field.is-disabled {
+    color: var(--color-text-disabled);
+    cursor: not-allowed;
+  }
+
+  .checkbox {
+    inline-size: var(--size-spacing-600);
+    block-size: var(--size-spacing-600);
+    margin: 0;
+    appearance: none;
+    display: inline-grid;
+    place-content: center;
+    border-style: solid;
+    border-width: var(--size-border-100);
+    border-color: var(--color-border-default);
+    border-radius: var(--brand-corner-input);
+    background: var(--color-fill-surface);
+    color: var(--color-text-inverse);
+    cursor: pointer;
+  }
+
+  .checkbox::after {
+    content: "";
+  }
+
+  .checkbox:checked,
+  .checkbox.is-checked {
+    border-color: var(--color-border-brand);
+    background: var(--color-fill-brand);
+  }
+
+  .checkbox:checked::after,
+  .checkbox.is-checked::after {
+    content: "\2713";
+    font-size: var(--typography-label-font-size);
+    line-height: var(--typography-label-line-height);
+  }
+
+  .checkbox:hover,
+  .checkbox.is-hover {
+    background:
+      linear-gradient(0deg, var(--color-overlay-hover), var(--color-overlay-hover)),
+      var(--color-fill-surface);
+    border-color: var(--color-border-brand);
+  }
+
+  .checkbox:checked:hover,
+  .checkbox.is-checked.is-hover {
+    background:
+      linear-gradient(0deg, var(--color-overlay-hover), var(--color-overlay-hover)),
+      var(--color-fill-brand);
+  }
+
+  .checkbox:active,
+  .checkbox.is-active {
+    background:
+      linear-gradient(0deg, var(--color-overlay-active), var(--color-overlay-active)),
+      var(--color-fill-surface);
+    border-color: var(--color-border-brand);
+    border-width: var(--size-border-200);
+  }
+
+  .checkbox:checked:active,
+  .checkbox.is-checked.is-active {
+    background:
+      linear-gradient(0deg, var(--color-overlay-active), var(--color-overlay-active)),
+      var(--color-fill-brand);
+  }
+
+  .checkbox:focus-visible,
+  .checkbox.is-focus-visible {
+    border-color: var(--color-border-brand);
+    outline: none;
+    box-shadow: 0 0 0 var(--shadow-focus, 0) var(--color-focus, transparent);
+  }
+
+  .checkbox:disabled,
+  .checkbox.is-disabled {
+    border-color: var(--color-border-disabled);
+    background: var(--color-fill-disabled);
+    color: var(--color-text-disabled);
+    cursor: not-allowed;
+  }
+}

package/dist/ui/patterns/icon.css

@@ -0,0 +1,20 @@
+@layer components {
+  .icon {
+    display: inline-block;
+    inline-size: 1em;
+    block-size: 1em;
+    inline-size: 1lh;
+    block-size: 1lh;
+    line-height: inherit;
+    background-color: currentColor;
+    -webkit-mask-image: var(--icon-src);
+    mask-image: var(--icon-src);
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+    -webkit-mask-position: center;
+    mask-position: center;
+    -webkit-mask-size: contain;
+    mask-size: contain;
+    vertical-align: middle;
+  }
+}

package/dist/ui/patterns/input.css

@@ -0,0 +1,76 @@
+@layer components {
+  .input {
+    inline-size: 100%;
+    block-size: var(--input-height, var(--size-spacing-800));
+    appearance: none;
+    font-family: var(--input-font-family);
+    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);
+    border-style: solid;
+    border-width: var(--input-border-size-default);
+    border-color: var(--input-text-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);
+  }
+
+  .input:hover,
+  .input.is-hover {
+    background:
+      linear-gradient(0deg, var(--input-overlay-hover), var(--input-overlay-hover)),
+      var(--input-text-container-background-default);
+    border-width: var(--input-border-size-hover);
+    padding-inline: calc(
+      var(--input-padding-inline) + var(--input-border-size-default) -
+        var(--input-border-size-hover)
+    );
+    padding-block: calc(
+      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);
+  }
+
+  .input:active,
+  .input.is-active {
+    background:
+      linear-gradient(0deg, var(--input-overlay-active), var(--input-overlay-active)),
+      var(--input-text-container-background-default);
+    border-width: var(--input-border-size-active);
+    padding-inline: calc(
+      var(--input-padding-inline) + var(--input-border-size-default) -
+        var(--input-border-size-active)
+    );
+    padding-block: calc(
+      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);
+  }
+
+  .input:focus-visible,
+  .input.is-focus-visible {
+    background: var(--input-text-container-background-focus);
+    border-color: var(--input-text-border-color-focus);
+    outline: none;
+    box-shadow: 0 0 0 var(--shadow-focus, 0) var(--color-focus, transparent);
+  }
+
+  .input:disabled,
+  .input[disabled],
+  .input.is-disabled {
+    cursor: not-allowed;
+    color: var(--input-text-color-disabled);
+    background: var(--input-container-background-disabled);
+    border-color: var(--input-border-color-disabled);
+  }
+}

package/dist/ui/patterns/label.css

@@ -0,0 +1,49 @@
+@layer components {
+  .label-content {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--label-gap, 0.5em);
+    line-height: inherit;
+  }
+
+  .label-content > .icon[data-slot] {
+    display: inline-flex;
+    align-items: center;
+    line-height: inherit;
+    flex: 0 0 auto;
+  }
+
+  .label-content__text {
+    line-height: inherit;
+  }
+
+  .label-content.is-icon-only {
+    gap: 0;
+  }
+
+  .field-label {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--field-label-gap, 0.25em);
+    line-height: var(--field-label-line-height, inherit);
+    cursor: pointer;
+  }
+
+  .field-label__required {
+    color: var(--field-label-required-color, currentColor);
+    font-weight: 700;
+  }
+
+  .field-label__required-text {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+}

package/docs/foundations/foundation-001-token-layering.md

@@ -0,0 +1,27 @@
+# Foundation-001: Token Layering Principles
+
+## Purpose
+
+Define a stable token architecture that:
+- aligns Figma Variables with CSS custom properties
+- supports Light/Dark modes and multiple brands
+- scales across components without duplication
+- remains maintainable and code-aligned
+
+## Rules
+
+1. Use four layers:
+   - **Core (Primitives)**: raw physical values (spacing, radii, borders, typography primitives, layout constants)
+   - **Color Modes (Light/Dark)**: raw color palettes (brand, neutral, overlays), no semantics
+   - **Semantics (Roles)**: meaning-based roles (`Color.Text.*`, `Color.Fill.*`, `Color.Border.*`, `Typography.*`, `Corner.*`)
+   - **Components (APIs)**: variants/parts/properties/states, referencing Semantic/Core tokens
+
+2. Components must not introduce raw values for color, typography, or layout fundamentals.
+
+3. Typography color must stay in semantic color roles, not inside typography role definitions.
+
+## Implications
+
+- Brand/mode changes happen primarily in Semantic/Mode mappings.
+- Component APIs remain stable while references evolve.
+- Layout constants (breakpoints, containers, z-index) stay centralized in Core.

package/docs/foundations/foundation-002-naming-and-grouping.md

@@ -0,0 +1,38 @@
+# Foundation-002: Naming and Grouping Conventions
+
+## Purpose
+
+Keep token naming readable in Figma, searchable in code, and scalable across variants/states.
+
+## Rules
+
+1. Component tokens follow a variant-first path:
+   `Component.variant.part.property.state`
+
+   Examples:
+   - `Button.solid.container.background.default`
+   - `Button.outline.container.border-color.hover`
+   - `Button.ghost.label.text-color.disabled`
+
+2. Semantic tokens remain role-based and component-agnostic:
+   - `Color.Text.Default`
+   - `Color.Fill.Surface`
+   - `Color.Border.Brand`
+   - `Typography.Label`
+   - `Corner.Medium`
+
+3. States are always the last segment:
+   `...property.state`
+
+   Common states:
+   `default`, `hover`, `active`, `focus`, `disabled`
+
+4. Naming style:
+   - Component name in PascalCase; subsequent segments in lowercase
+   - Multi-word properties in kebab-case (`border-color`, `line-height`)
+   - No device labels (`mobile/tablet/desktop`) in token names
+
+## Implications
+
+- Figma browsing remains predictable.
+- Token APIs stay implementation-friendly while preserving semantic clarity.

package/docs/foundations/foundation-003-color-semantics-and-status.md

@@ -0,0 +1,35 @@
+# Foundation-003: Color Semantics, Status vs State
+
+## Purpose
+
+Provide a color model that supports brand/mode mapping and semantic meaning without component-level duplication.
+
+## Rules
+
+1. Keep raw palettes separate from semantics:
+   - `Brand.*`, `Neutral.*`, `Overlay.*` provide raw color sources
+   - `Color.Text.*`, `Color.Fill.*`, `Color.Border.*` provide semantic roles per mode
+
+2. Semantic mappings are mode-scoped:
+   - Light mappings at `:root`
+   - Dark mappings at `:root[data-mode="dark"]`
+   - Mode activation policy is consumer-owned (see Foundation-008)
+
+3. Status is semantic meaning (global):
+   - `Danger`, optionally `Warning`, `Success`, `Info`
+   - Applied across role families (Text/Fill/Border)
+
+4. State is interaction behavior (component-level):
+   - `...background.hover`
+   - `...border-color.focus`
+   - `...text-color.disabled`
+
+5. Support inverse readability via semantic roles where needed:
+   - `Color.Text.Inverse`
+   - optional `Color.Fill.Inverse`
+
+## Implications
+
+- Semantic APIs stay stable across modes.
+- Components keep interaction logic without polluting global semantics.
+- Multi-brand, multi-mode theming remains flexible.

package/docs/foundations/foundation-004-typography-scale-and-line-height.md

@@ -0,0 +1,39 @@
+# Foundation-004: Typography Scale and Line Height
+
+## Purpose
+
+Align typography between Figma and CSS with a predictable rhythm.
+
+## Rules
+
+1. Core typography primitives define:
+   - `Font.Size.*` (px)
+   - `LineHeight.*` (px, aligned to 4px grid)
+   - `Font.Weight.*`
+   - `Font.Family.*`
+
+2. Line-height target:
+   - Use a 140% target
+   - Round to nearest 4px grid for published line-height primitives
+
+3. Semantic typography roles (`Typography.*`) bundle:
+   - font-family
+   - font-size
+   - line-height
+   - font-weight
+
+   Example scale:
+   - xs (12) -> xs (16)
+   - sm (14) -> sm (20)
+   - md (16) -> md (24)
+   - lg (20) -> lg (28)
+   - xl (24) -> xl (32)
+   - 2xl (32) -> 2xl (44)
+   - 3xl (40) -> 3xl (56)
+
+4. Typography roles must not include color; text color belongs to `Color.Text.*`.
+
+## Implications
+
+- Designers and engineers share the same typographic rhythm.
+- Typography tokens remain reusable across components.

package/docs/foundations/foundation-005-responsive-breakpoints-and-containers.md

@@ -0,0 +1,23 @@
+# Foundation-005: Responsive Strategy (Breakpoints and Containers)
+
+## Purpose
+
+Keep responsive thresholds precise, stable, and reusable across viewport and component contexts.
+
+## Rules
+
+1. Viewport breakpoints are Core primitives:
+   - `Core.Breakpoint.*` (px)
+
+2. Container query thresholds are separate Core primitives:
+   - `Core.Container.*` (px)
+
+3. Breakpoints and container thresholds are not interchangeable.
+
+4. Avoid device names and t-shirt sizes in Core tokens.
+   Numeric thresholds are the source of truth.
+
+## Implications
+
+- Clear separation between page-level and component-level responsiveness.
+- Better long-term maintainability for responsive behavior.

package/docs/foundations/foundation-006-z-index-layering.md

@@ -0,0 +1,31 @@
+# Foundation-006: Z-Index and Layering Strategy
+
+## Purpose
+
+Ensure predictable stacking behavior without scattered magic numbers.
+
+## Rules
+
+1. Define z-index values as Core primitives under `Core.ZIndex.*`.
+
+2. Recommended base levels:
+   - `Core.ZIndex.Hidden = -1`
+   - `Core.ZIndex.Base = 0`
+   - `Core.ZIndex.Raised = 1`
+
+3. Recommended overlay stack:
+   - `Core.ZIndex.DropdownBase = 900`
+   - `Core.ZIndex.Dropdown = 1000`
+   - `Core.ZIndex.Sticky = 1020`
+   - `Core.ZIndex.Fixed = 1030`
+   - `Core.ZIndex.ModalOverlay = 1040`
+   - `Core.ZIndex.Modal = 1050`
+   - `Core.ZIndex.Popover = 1060`
+   - `Core.ZIndex.Tooltip = 1070`
+
+4. Components must reference these tokens and must not introduce new stacking numbers.
+
+## Implications
+
+- Layering remains predictable across components and products.
+- Z-index conflicts are reduced.