@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/tokens.usage.json

@@ -102,10 +102,7 @@
         "section heading text color"
       ],
       "maxInstancesPerScreen": 3,
-      "maxInstancesRationale": "Brand red is a marker — more than 3 instances per screen dilute its meaning. The canonical instances are: the Create entry on tab-bar (1), an active-like state inside a feed item (≤2), an optional promotional banner accent (1).",
-      "value": "#d92626",
-      "darkValue": "#d92626",
-      "unit": "hex"
+      "maxInstancesRationale": "Brand red is a marker — more than 3 instances per screen dilute its meaning. The canonical instances are: the Create entry on tab-bar (1), an active-like state inside a feed item (≤2), an optional promotional banner accent (1)."
     },
     "sys.color.brandContainer": {
       "role": "Tinted brand surface — promotional accent without full saturation.",
@@ -116,10 +113,7 @@
       "notFor": [
         "primary CTA"
       ],
-      "pairsWith": "sys.color.onBrandContainer",
-      "value": "#faf2f2",
-      "darkValue": "#350a0a",
-      "unit": "hex"
+      "pairsWith": "sys.color.onBrandContainer"
     },
     "sys.color.elevation": {
       "role": "Elevation shadow color (compose into box-shadow).",
@@ -128,10 +122,7 @@
       ],
       "notFor": [
         "visible fills"
-      ],
-      "value": "#000000",
-      "darkValue": "#000000",
-      "unit": "hex"
+      ]
     },
     "sys.color.error": {
       "role": "Red destructive / error commit color — never used for emphasis, only for destructive actions or error states.",
@@ -156,10 +147,7 @@
         "default body text",
         "tab-bar/* (Create item uses brand)",
         "promotional surfaces (use brand)"
-      ],
-      "value": "#b42222",
-      "darkValue": "#931a1a",
-      "unit": "hex"
+      ]
     },
     "sys.color.errorContainer": {
       "role": "Tinted-red surface — destructive banner / error notice.",
@@ -168,10 +156,7 @@
         "destructive callout"
       ],
       "notFor": [],
-      "pairsWith": "sys.color.onErrorContainer",
-      "value": "#f5dbdb",
-      "darkValue": "#350a0a",
-      "unit": "hex"
+      "pairsWith": "sys.color.onErrorContainer"
     },
     "sys.color.focus": {
       "role": "Focus ring outer stroke color.",
@@ -181,10 +166,7 @@
       "notFor": [
         "body text",
         "interactive fills"
-      ],
-      "value": "#000000",
-      "darkValue": "#ffffff",
-      "unit": "hex"
+      ]
     },
     "sys.color.focusInset": {
       "role": "Focus ring inner counter-ring color — paints between the focus stroke and the control.",
@@ -193,10 +175,7 @@
       ],
       "notFor": [
         "body text"
-      ],
-      "value": "#ffffff",
-      "darkValue": "#000000",
-      "unit": "hex"
+      ]
     },
     "sys.color.inverseOnSurface": {
       "role": "Foreground on inverseSurface — Toast text.",
@@ -205,10 +184,7 @@
       ],
       "notFor": [
         "default body text"
-      ],
-      "value": "#fafafa",
-      "darkValue": "#141414",
-      "unit": "hex"
+      ]
     },
     "sys.color.inverseSurface": {
       "role": "Inverse-theme surface — Toast background sits on this.",
@@ -217,48 +193,33 @@
       ],
       "notFor": [
         "default page surface"
-      ],
-      "value": "#141414",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      ]
     },
     "sys.color.onBrand": {
       "role": "Foreground on sys.color.brand fills.",
       "usedFor": [
         "icon/label on a brand-filled FAB or banner"
       ],
-      "notFor": [],
-      "value": "#fafafa",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onBrandContainer": {
       "role": "Foreground on brandContainer surfaces.",
       "usedFor": [
         "label on brandContainer fills"
       ],
-      "notFor": [],
-      "value": "#b42222",
-      "darkValue": "#df5656",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onError": {
       "role": "Foreground on error fills.",
       "usedFor": [
         "label on a destructive-filled button"
       ],
-      "notFor": [],
-      "value": "#fafafa",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onErrorContainer": {
       "role": "Foreground on errorContainer.",
       "usedFor": [],
-      "notFor": [],
-      "value": "#931a1a",
-      "darkValue": "#d92626",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onPrimary": {
       "role": "Foreground that paints ON sys.color.primary fills. Travels as a pair.",
@@ -268,10 +229,7 @@
       ],
       "notFor": [
         "any surface that isn't sys.color.primary"
-      ],
-      "value": "#fafafa",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      ]
     },
     "sys.color.onPrimaryContainer": {
       "role": "Foreground for primaryContainer surfaces. Travels as a pair.",
@@ -280,10 +238,7 @@
       ],
       "notFor": [
         "primary fills (use onPrimary)"
-      ],
-      "value": "#1d4ed8",
-      "darkValue": "#5081ed",
-      "unit": "hex"
+      ]
     },
     "sys.color.onSecondary": {
       "role": "Foreground on sys.color.secondary fills.",
@@ -292,38 +247,26 @@
       ],
       "notFor": [
         "surfaces other than secondary"
-      ],
-      "value": "#fafafa",
-      "darkValue": "#141414",
-      "unit": "hex"
+      ]
     },
     "sys.color.onSecondaryContainer": {
       "role": "Foreground on secondaryContainer surfaces.",
       "usedFor": [
         "label on secondaryContainer fills"
       ],
-      "notFor": [],
-      "value": "#141414",
-      "darkValue": "#f0f0f0",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onSuccess": {
       "role": "Foreground on success fills.",
       "usedFor": [
         "label on a success-filled surface"
       ],
-      "notFor": [],
-      "value": "#fafafa",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onSuccessContainer": {
       "role": "Foreground on successContainer.",
       "usedFor": [],
-      "notFor": [],
-      "value": "#006d2c",
-      "darkValue": "#25b260",
-      "unit": "hex"
+      "notFor": []
     },
     "sys.color.onSurface": {
       "role": "Default body text color — what most text on a `surface` fill resolves to.",
@@ -334,10 +277,7 @@
       ],
       "notFor": [
         "primary CTA label on primary fill (use onPrimary)"
-      ],
-      "value": "#141414",
-      "darkValue": "#fafafa",
-      "unit": "hex"
+      ]
     },
     "sys.color.onSurfaceVariant": {
       "role": "Secondary text color — meta lines, supporting text, placeholders, glyph chrome.",
@@ -350,10 +290,7 @@
       ],
       "notFor": [
         "primary body text (use onSurface)"
-      ],
-      "value": "#3d3d3d",
-      "darkValue": "#c2c2c2",
-      "unit": "hex"
+      ]
     },
     "sys.color.outline": {
       "role": "Strong divider line — control boundary, full-emphasis border.",
@@ -363,10 +300,7 @@
       ],
       "notFor": [
         "hairline card stroke (use outlineVariant)"
-      ],
-      "value": "#999999",
-      "darkValue": "#737373",
-      "unit": "hex"
+      ]
     },
     "sys.color.outlineVariant": {
       "role": "Hairline edge stroke — card outline, divider line between rows.",
@@ -377,32 +311,7 @@
       ],
       "notFor": [
         "form field active stroke (use outline or primary)"
-      ],
-      "value": "#e0e0e0",
-      "darkValue": "#3d3d3d",
-      "unit": "hex"
-    },
-    "sys.color.placeholderImage.end": {
-      "role": "Gradient end for the placeholder image-area underlay.",
-      "usedFor": [
-        "image-area underlay gradient end"
-      ],
-      "notFor": [],
-      "value": "#2d6f72",
-      "darkValue": "#1a2226",
-      "unit": "hex"
-    },
-    "sys.color.placeholderImage.start": {
-      "role": "Gradient start for the placeholder image-area underlay (when /placeholder.png itself is unavailable).",
-      "usedFor": [
-        "image-area underlay gradient start"
-      ],
-      "notFor": [
-        "foreground content"
-      ],
-      "value": "#c8e0e1",
-      "darkValue": "#3a4548",
-      "unit": "hex"
+      ]
     },
     "sys.color.primary": {
       "role": "Brand-blue commit color — primary CTAs, active selection, link affordance.",
@@ -432,10 +341,7 @@
         "card outline (use outlineVariant)",
         "list-row divider (use outlineVariant)",
         "tab-bar/* (Create item uses brand, other items use onSurface)"
-      ],
-      "value": "#2563eb",
-      "darkValue": "#2563eb",
-      "unit": "hex"
+      ]
     },
     "sys.color.primaryContainer": {
       "role": "Tinted-primary surface for low-emphasis primary tints — informational chips, soft callouts.",
@@ -447,10 +353,7 @@
       "notFor": [
         "primary commit button (use primary)"
       ],
-      "pairsWith": "sys.color.onPrimaryContainer",
-      "value": "#f1f4fb",
-      "darkValue": "#0a1833",
-      "unit": "hex"
+      "pairsWith": "sys.color.onPrimaryContainer"
     },
     "sys.color.scrim": {
       "role": "Dialog / BottomSheet scrim background — semi-transparent black overlay.",
@@ -460,10 +363,7 @@
       ],
       "notFor": [
         "any visible surface"
-      ],
-      "value": "#000000a3",
-      "darkValue": "#000000a3",
-      "unit": "hex"
+      ]
     },
     "sys.color.scrimSubtle": {
       "role": "Translucent inverse-tone surface tint (~8% — black light / white dark). Surface-agnostic fill that stays visible on every host surface tier.",
@@ -477,10 +377,7 @@
       "notFor": [
         "modal backdrop (use scrim)",
         "opaque container surfaces (use surface* ladder)"
-      ],
-      "value": "#00000014",
-      "darkValue": "#ffffff14",
-      "unit": "hex"
+      ]
     },
     "sys.color.secondary": {
       "role": "Neutral-dark accent — secondary text, neutral active state, supporting metric.",
@@ -493,10 +390,7 @@
         "primary commit (use primary)",
         "body text on surface (use onSurface)"
       ],
-      "pairsWith": "sys.color.onSecondary",
-      "value": "#3d3d3d",
-      "darkValue": "#c2c2c2",
-      "unit": "hex"
+      "pairsWith": "sys.color.onSecondary"
     },
     "sys.color.secondaryContainer": {
       "role": "Tinted neutral surface — soft secondary tint.",
@@ -507,10 +401,7 @@
       "notFor": [
         "plain card surface (use surface)"
       ],
-      "pairsWith": "sys.color.onSecondaryContainer",
-      "value": "#f0f0f0",
-      "darkValue": "#525252",
-      "unit": "hex"
+      "pairsWith": "sys.color.onSecondaryContainer"
     },
     "sys.color.success": {
       "role": "Green commit / status color — success states, positive metrics.",
@@ -534,10 +425,7 @@
         "button fill (primary commits use primary; destructive uses error)",
         "navigation-bar/*",
         "default body text"
-      ],
-      "value": "#008838",
-      "darkValue": "#008838",
-      "unit": "hex"
+      ]
     },
     "sys.color.successContainer": {
       "role": "Tinted-green surface — success banner background.",
@@ -546,10 +434,7 @@
         "completed-state callout"
       ],
       "notFor": [],
-      "pairsWith": "sys.color.onSuccessContainer",
-      "value": "#f0faf3",
-      "darkValue": "#00200a",
-      "unit": "hex"
+      "pairsWith": "sys.color.onSuccessContainer"
     },
     "sys.color.surface": {
       "role": "Default page and card fill — the canvas every other surface paints over.",
@@ -562,10 +447,7 @@
       "notFor": [
         "tinted callouts (use *Container variants)"
       ],
-      "pairsWith": "sys.color.onSurface",
-      "value": "#ffffff",
-      "darkValue": "#141414",
-      "unit": "hex"
+      "pairsWith": "sys.color.onSurface"
     },
     "sys.color.surfaceBright": {
       "role": "Light-mode bright surface step — used in dark mode to invert to a near-white surface.",
@@ -574,10 +456,7 @@
       ],
       "notFor": [
         "light-mode default fill"
-      ],
-      "value": "#ffffff",
-      "darkValue": "#262626",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceContainer": {
       "role": "Mid-tint surface for grouped content blocks — Feed citation card, neutral grouped surface.",
@@ -587,10 +466,7 @@
       ],
       "notFor": [
         "page background (use surface)"
-      ],
-      "value": "#ffffff",
-      "darkValue": "#262626",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceContainerHigh": {
       "role": "Higher tint than surface — banner backgrounds, ProfileCarousel cover band, image-area fallback.",
@@ -601,10 +477,7 @@
       ],
       "notFor": [
         "page background"
-      ],
-      "value": "#ffffff",
-      "darkValue": "#262626",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceContainerHighest": {
       "role": "Highest neutral surface tint — pressed-state row fill, deepest neutral callout.",
@@ -614,10 +487,7 @@
       ],
       "notFor": [
         "default fill"
-      ],
-      "value": "#ffffff",
-      "darkValue": "#3d3d3d",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceContainerLow": {
       "role": "Slight tint below default surface — search input bar fill, hover-state row fill.",
@@ -627,10 +497,7 @@
       ],
       "notFor": [
         "card fill (use surface)"
-      ],
-      "value": "#f0f0f0",
-      "darkValue": "#141414",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceContainerLowest": {
       "role": "Deepest-low tint — barely visible surface step. Reserved for very subtle separation.",
@@ -639,10 +506,7 @@
       ],
       "notFor": [
         "any default fill"
-      ],
-      "value": "#f0f0f0",
-      "darkValue": "#000000",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceDim": {
       "role": "Dimmer-than-default surface — slightly muted variant.",
@@ -651,10 +515,7 @@
       ],
       "notFor": [
         "default fill"
-      ],
-      "value": "#e0e0e0",
-      "darkValue": "#141414",
-      "unit": "hex"
+      ]
     },
     "sys.color.surfaceVariant": {
       "role": "Subtly-tinted surface variant — input field rest fill, low-emphasis surface.",
@@ -665,10 +526,7 @@
       "notFor": [
         "page background (use surface)"
       ],
-      "pairsWith": "sys.color.onSurfaceVariant",
-      "value": "#f0f0f0",
-      "darkValue": "#262626",
-      "unit": "hex"
+      "pairsWith": "sys.color.onSurfaceVariant"
     },
     "sys.elevation.floating": {
       "role": "Free-floating above the page.",
@@ -699,20 +557,6 @@
       "darkValue": "0 4px 12px #00000014, 0 16px 48px #00000033",
       "unit": "shadow"
     },
-    "sys.elevation.raised": {
-      "role": "Subtle lift — sits-on the page.",
-      "usedFor": [
-        "card at rest",
-        "hovered list rows",
-        "selected menu items"
-      ],
-      "notFor": [
-        "modal surfaces (use floating/overlay)"
-      ],
-      "value": "0 1px 2px #0000000a, 0 2px 6px #0000000f",
-      "darkValue": "0 1px 2px #0000000a, 0 2px 6px #0000000f",
-      "unit": "shadow"
-    },
     "sys.elevation.sheet": {
       "role": "Edge-anchored panel projecting shadow upward (or away from the anchored edge).",
       "usedFor": [
@@ -1350,13 +1194,13 @@
         "mixed-group section body (use body.md or sm)"
       ],
       "value": {
-        "size": "20px",
+        "size": "18px",
         "weight": 400,
         "line": 1.5,
         "tracking": "0em"
       },
       "darkValue": {
-        "size": "20px",
+        "size": "18px",
         "weight": 400,
         "line": 1.5,
         "tracking": "0em"
@@ -1399,41 +1243,17 @@
       "value": {
         "size": "14px",
         "weight": 400,
-        "line": 1.5,
+        "line": 1.35,
         "tracking": "0em"
       },
       "darkValue": {
         "size": "14px",
         "weight": 400,
-        "line": 1.5,
+        "line": 1.35,
         "tracking": "0em"
       },
       "unit": "object"
     },
-    "sys.typo.caption": {
-      "role": "Caption (10px, weight 600) — smallest text rung; tiny annotation, badge count.",
-      "usedFor": [
-        "tiny annotation",
-        "badge count",
-        "smallest legal/aux line"
-      ],
-      "notFor": [
-        "any primary or meta text"
-      ],
-      "value": {
-        "size": "10px",
-        "weight": 600,
-        "line": 1.5,
-        "tracking": "0.02em"
-      },
-      "darkValue": {
-        "size": "10px",
-        "weight": 600,
-        "line": 1.5,
-        "tracking": "0.02em"
-      },
-      "unit": "object"
-    },
     "sys.typo.display.lg": {
       "role": "Largest display type (48→80px) — landing page hero headline.",
       "usedFor": [
@@ -1542,13 +1362,13 @@
         "list-row label (use body.md)"
       ],
       "value": {
-        "size": "20px",
+        "size": "18px",
         "weight": 600,
         "line": 1.25,
         "tracking": "-0.01em"
       },
       "darkValue": {
-        "size": "20px",
+        "size": "18px",
         "weight": 600,
         "line": 1.25,
         "tracking": "-0.01em"
@@ -1652,6 +1472,31 @@
         "tracking": "0.02em"
       },
       "unit": "object"
+    },
+    "sys.typo.label.xs": {
+      "role": "Smallest label rung (10px, weight 600) — caption-scale text; tiny annotation, badge count, tab-bar label.",
+      "usedFor": [
+        "tiny annotation",
+        "badge count",
+        "tab-bar label",
+        "smallest legal/aux line"
+      ],
+      "notFor": [
+        "any primary or meta text"
+      ],
+      "value": {
+        "size": "10px",
+        "weight": 600,
+        "line": 1.5,
+        "tracking": "0.02em"
+      },
+      "darkValue": {
+        "size": "10px",
+        "weight": 600,
+        "line": 1.5,
+        "tracking": "0.02em"
+      },
+      "unit": "object"
     }
   }
 }

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",