@teamblind-chorus/ui 1.1.0 → 1.2.0

package/agents/components/spinner/spinner.md

@@ -0,0 +1,98 @@
+# Spinner
+
+> 🇰🇷 한국어: [`i18n/ko/schema/components/spinner/spinner.md`](../../../i18n/ko/schema/components/spinner/spinner.md)
+
+An indeterminate loading indicator — a rotating arc in `sys.color.primary` over a faint `scrimSubtle` ring that signals a short, progress-unknown wait on a neutral host surface. Two rungs ride the `icon.*` ladder — `medium` (24px, default) and `small` (16px). Pass a `label` for a single line of loading copy beside the arc.
+
+**Reach for this when** a wait is brief and indeterminate (under ~1 second) — a button submit, an inline action, or a first-paint loader before a screen's data resolves — and a content-shaped placeholder would be heavier than the wait itself. **Skip when** the wait mirrors a known shape (use [Skeleton](../skeleton/skeleton.md)), the task has a measurable ratio (use [Progress](../progress/progress.md)), or the surface already shows another Spinner — reserve one per view.
+
+**Layout inset.** `inline` — Spinner ships no padding or container chrome of its own. It sits as a leaf at the size of its rung; the host owns centering and surrounding rhythm. An optional label sits beside the arc with `sys.layout.inline.sm` between them.
+
+## Default
+
+A 24px rotating arc. `role='status'` announces the loading state; `aria-label` defaults to `'Loading'`.
+
+```preview
+spinner/default
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner aria-label="Loading" />
+```
+
+## Use cases
+
+### With label
+
+A single line of loading copy beside the arc. The label doubles as the accessible name, so `aria-label` is not needed.
+
+```preview
+spinner/with-label
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner label="Loading…" />
+```
+
+### Small
+
+The 16px rung — for tight inline affordances (a button label, a form-field affix) where the 24px default would crowd.
+
+```preview
+spinner/small
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner size="small" aria-label="Loading" />
+```
+
+### Centered
+
+A first-paint loader centered inside the surface that will hold the data. One Spinner per view.
+
+```preview
+spinner/centered
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', justifyContent: 'center', padding: 'var(--sys-layout-container-xl)' }}>
+  <Spinner label="Loading…" />
+</div>
+```
+
+## Slots
+
+- **container** — inline-flex wrapper. Carries `role='status'` and the accessible name; holds the arc and the optional label, separated by `sys.layout.inline.sm`.
+- **arc** — the rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke. Carries the spin animation. Decorative (`aria-hidden`).
+- **label** — optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`.
+
+## Anatomy
+
+| Slot       | Token bindings |
+|------------|----------------|
+| container  | inline-flex, `sys.layout.inline.sm` gap between arc and label |
+| arc        | `sys.color.primary` foreground arc, `sys.color.scrimSubtle` track ring, `sys.radius.full`, no stroke |
+| medium     | `sys.icon.lg` (24px) diameter — the default rung |
+| small      | `sys.icon.md` (16px) diameter |
+| label      | `sys.typo.body.sm`, `sys.color.onSurfaceVariant` |
+
+## Sizes
+
+| Size     | Diameter            | When to reach |
+|----------|---------------------|---------------|
+| `medium` | `sys.icon.lg` (24px) | **Default**. Standalone or centered first-paint loaders. |
+| `small`  | `sys.icon.md` (16px) | Tight inline affordances — button labels, form-field affixes. |
+
+## States
+
+| State          | Animation                       | Notes |
+|----------------|---------------------------------|-------|
+| `default`      | `rotate 0.8s linear infinite`   | The arc spins continuously. Indeterminate — the rotation never reflects a value. |
+| reduced-motion | suppressed                      | Under `prefers-reduced-motion: reduce` the spin halts and the full ring shows statically. |
+
+## Behavior
+
+- **Indeterminate only.** The rotation never maps to a ratio — for a known percentage use [Progress](../progress/progress.md).
+- **One per view.** Reserve a single Spinner per screen; concurrent regional waits use [Skeleton](../skeleton/skeleton.md) or lift to one screen-level Spinner.
+- **Accessible name.** `role='status'` announces loading without interrupting focus. A visible `label` doubles as the name; otherwise `aria-label` (default `'Loading'`) carries it. The arc is decorative.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce` the spin is suppressed; the full ring shows statically as a quiet loading mark.

package/agents/components/spinner/spinner.spec.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Spinner",
+  "family": "spinner",
+  "description": "A rotating arc that signals an indeterminate, sub-second wait on a neutral host surface. The arc paints in `sys.color.primary` as the foreground motion and spins continuously over a faint `sys.color.scrimSubtle` ring so the rotation reads on any surface tier. Two rungs ride the `icon.*` ladder — `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot places a single line of loading copy beside the arc. `role='status'` + an accessible name (`aria-label`, default `'Loading'`) announce the loading state. Indeterminate only — for a known ratio use Progress; for content-shaped waits use Skeleton.",
+  "element": "span",
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": ["medium", "small"],
+      "default": "medium",
+      "description": "Selects the arc diameter off the `icon.*` ladder. `medium` paints at `sys.icon.lg` (24px); `small` at `sys.icon.md` (16px)."
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. When present it also supplies the accessible name, so `aria-label` is not required."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label announced by screen readers. Defaults to `'Loading'`. Supply a more specific name (e.g. `'Signing in'`) when the wait scope is meaningful. Redundant when a visible `label` is passed."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Inline-flex wrapper carrying `role='status'` and the accessible name. Holds the arc and the optional label, separated by `sys.layout.inline.sm`.",
+      "intrinsic": true
+    },
+    "arc": {
+      "required": true,
+      "description": "The rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke border. Carries the continuous spin animation. Decorative — `aria-hidden`.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": false,
+      "description": "Optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`.",
+      "omittedBehavior": "collapse"
+    }
+  },
+  "sizes": {
+    "medium": {
+      "diameter": "sys.icon.lg",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    },
+    "small": {
+      "diameter": "sys.icon.md",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    }
+  },
+  "appearances": {
+    "default": {
+      "arc": "sys.color.primary",
+      "track": "sys.color.scrimSubtle",
+      "label": "sys.color.onSurfaceVariant",
+      "note": "The only appearance. The foreground arc paints `sys.color.primary` for the motion accent; the track ring paints `sys.color.scrimSubtle` (a faint inverse-tone scrim — ~8% black light / ~8% white dark) so the rotation reads on any host surface tier. Spinner has no emphasis axis — for a higher-attention loading mark the emphasis belongs in adjacent copy, not in a chromatic arc swap."
+    }
+  },
+  "states": {
+    "default": {
+      "animation": "chorus-spinner-rotate 0.8s linear infinite",
+      "note": "The arc rotates continuously at 0.8s per turn (well below the WCAG flash threshold — rotation modulates position, not luminance). Indeterminate: the rotation never reflects a value. The animation respects `prefers-reduced-motion: reduce` — the spin halts and the full ring is shown statically as a quiet loading mark."
+    }
+  },
+  "behavior": {
+    "ariaStatus": "Container carries `role='status'` and the accessible name (visible `label` or `aria-label`, default `'Loading'`) so screen readers announce the loading state without yanking focus. The arc is decorative (`aria-hidden`).",
+    "reducedMotion": "Under `@media (prefers-reduced-motion: reduce)` the spin is suppressed; the full ring shows statically as a quiet loading mark.",
+    "singleInstance": "Reserve one Spinner per view. Concurrent regional waits stack visual noise — lift to a single screen-level Spinner or switch the inner waits to Skeleton.",
+    "labelComposition": "Pass `label` for visible loading copy beside the arc; it doubles as the accessible name. Without a label, `aria-label` (default `'Loading'`) carries the announcement."
+  },
+  "forbidden": [
+    "Spinner bound to a known progress ratio / percentage — indeterminate only; a determinate value belongs to `progress`",
+    "more than one Spinner visible in a single view — reserve to one per view; concurrent regional waits use `skeleton` or lift to a single screen-level Spinner",
+    "Spinner used as a content-shaped placeholder (list row, feed card, avatar) — that role is `skeleton`, which mirrors the footprint of the data being fetched",
+    "arc painted with a non-token hex / raw px diameter — the arc tone is `sys.color.primary` and the diameter rides the `icon.*` ladder (`sys.icon.md` / `sys.icon.lg`)",
+    "shimmer / gradient sweep on the arc — Spinner modulates rotation only (one motion axis keeps it readable under the reduced-motion fallback)",
+    "arc track or ring drawn with a `border:` — the ring draws as a `box-shadow` / conic fill, not a layout stroke"
+  ]
+}

package/agents/components/switch/switch.spec.json

@@ -88,6 +88,15 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.focusInset" },
+        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual — a three-layer outward ring on the track's outer edge, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the control is in."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "pointerEvents": "none",

package/agents/components/tab-bar/tab-bar.spec.json

@@ -142,6 +142,22 @@
       "description": "Active press on the item. State layer fills the slot, painted with `onSurface` at `sys.state.pressed` (12%).",
       "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.pressed)"
     },
+    "focused": {
+      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.focus)",
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. State layer fills the slot with `onSurface` at `sys.state.focus` (12%); the three-layer ring is forced inward (adjacent items are flush under flex:1 1 0). Mirrors the `focusIndicator` block for spec-only renderers. Single-focus: at most one item holds the ring."
+    },
     "active": {
       "description": "Currently selected destination. Filled glyph (`activeIcon`) + label, both at `onSurface`. Carries `aria-current='page'`. No persistent state layer — only hover / pressed / focus paint."
     },

package/agents/components/tabs/rounded.spec.json

@@ -106,6 +106,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the tab is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/tabs/underline.spec.json

@@ -103,6 +103,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the tab is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/manifest.json

@@ -39,15 +39,15 @@
       "styles": "packages/ui/src/styles.css",
       "iconsExportSubpath": "@teamblind-chorus/ui/icons",
       "stylesExportSubpath": "@teamblind-chorus/ui/styles.css",
-      "published": false,
-      "distribution": "source",
-      "note": "Workspace-only, source-distributed. External tools either (a) read JSX directly from `entry` (compile JSX themselves) or (b) consume the structural contract via `schema/components/<family>/<sub>.spec.json` and re-render with their own renderer. Either path MUST also load `styles.css` once at the app entry — the JSX emits inline `--<component>-*` plumbing vars but expects the static rules in `styles.css` to receive them. The package is marked `private: true` and intentionally pinned at version `0.0.0` until a publishing decision is made."
+      "published": true,
+      "distribution": "npm",
+      "note": "Published to npm as `@teamblind-chorus/ui` (built `dist/` — compiled components, type declarations, and CSS). External tools either (a) install the package and import its components, or (b) consume the structural contract via `schema/components/<family>/<sub>.spec.json` and re-render with their own renderer. Either path MUST also load `@teamblind-chorus/ui/styles.css` once at the app entry — components emit inline `--<component>-*` plumbing vars but expect the static rules in `styles.css` to receive them."
     },
     "tokens": {
       "name": "@teamblind-chorus/tokens",
-      "published": false,
-      "distribution": "source",
-      "note": "Workspace-only. External tools should prefer the `tokens.resolved.*` bundles above over the three-tier source files unless they specifically need the reference graph."
+      "published": true,
+      "distribution": "npm",
+      "note": "Published to npm as `@teamblind-chorus/tokens`. External tools should prefer the `tokens.resolved.*` bundles above over the three-tier source files unless they specifically need the reference graph."
     }
   },
   "components": [
@@ -62,6 +62,7 @@
     { "family": "dialog",         "root": "components/dialog/dialog.family.json" },
     { "family": "divider",        "root": "components/divider/divider.family.json" },
     { "family": "directory-list", "root": "components/directory-list/directory-list.family.json" },
+    { "family": "empty-state",    "root": "components/empty-state/empty-state.family.json" },
     { "family": "feed",           "root": "components/feed/feed.family.json" },
     { "family": "form-field",     "root": "components/form-field/form-field.family.json" },
     { "family": "header",         "root": "components/header/header.family.json" },
@@ -77,6 +78,7 @@
     { "family": "carousel",       "root": "components/carousel/carousel.family.json" },
     { "family": "side-sheet",     "root": "components/side-sheet/side-sheet.family.json" },
     { "family": "skeleton",       "root": "components/skeleton/skeleton.family.json" },
+    { "family": "spinner",        "root": "components/spinner/spinner.family.json" },
     { "family": "status-tag",     "root": "components/status-tag/status-tag.family.json" },
     { "family": "switch",         "root": "components/switch/switch.family.json" },
     { "family": "tab-bar",        "root": "components/tab-bar/tab-bar.family.json" },

package/agents/usage.json

@@ -156,6 +156,12 @@
       "note": "Rows are an `items` array of descriptors (name/followers/description/thumbnail/active/onToggle) — there are NO List or row children.",
       "example": "<DirectoryList label=\"…\" items={[{ value, name, followers, description, thumbnail: { src, alt }, active, onToggle }]} />"
     },
+    "empty-state": {
+      "import": "EmptyState",
+      "from": "@teamblind-chorus/ui",
+      "note": "Headline is the `headline` prop (required); `body` is the `body` prop; the CTA is the `action` object ({ label, href?/onClick? }) which renders a default-size primary Button — there is NO `cta` slot to fill with your own button. Pass an icon node to `illustration`.",
+      "example": "<EmptyState illustration={<ChatIcon />} headline=\"No posts yet\" body=\"Conversations you start or join will appear here.\" action={{ label: 'Start a post', onClick: () => {} }} />"
+    },
     "feed": {
       "import": "Feed",
       "from": "@teamblind-chorus/ui",
@@ -363,6 +369,12 @@
       "note": "shape defaults to text; width/height are consumer-supplied. Stack multiples in SkeletonGroup to mirror the loading content's rhythm.",
       "example": "<Skeleton shape=\"block\" height={120} />"
     },
+    "spinner": {
+      "import": "Spinner",
+      "from": "@teamblind-chorus/ui",
+      "note": "indeterminate only — never bind it to a progress ratio (use Progress). Reserve to one Spinner per view. aria-label defaults to 'Loading'; pass a label child for visible loading copy beside the arc.",
+      "example": "<Spinner aria-label=\"Loading\" />"
+    },
     "status-tag": {
       "import": "StatusTag",
       "from": "@teamblind-chorus/ui",