@cube-dev/ui-kit 0.0.0-canary-5edde72 → 0.0.0-canary-5133ea8

package/docs/Colors.md

@@ -0,0 +1,77 @@
+# Colors
+
+Cube UI Kit color tokens are generated by Glaze from a shared OKHST palette.
+Every adaptive token includes light, dark, and high-contrast variants. Change
+the active scheme in the Storybook toolbar to review each example.
+
+## Choosing a color pair
+
+Start with the surface, then choose a foreground designed for that surface:
+
+- On neutral surfaces, use the matching text family:
+  `#surface` + `#surface-text`, `#surface-2` + `#surface-2-text`, and so on.
+- On semantic tinted surfaces, use `#<theme>-surface-text` for a neutralized,
+  high-contrast foreground.
+- Use `#<theme>-accent-text` or `-soft` when the foreground should retain the
+  semantic hue, such as notification titles and links.
+- On solid accent fills, use `#<theme>-accent-surface-text`.
+- Do not select colors only because they look similar. Their names describe
+  the contrast relationship and intended role.
+
+The text examples show each color with `t3m`, `t3`, and `t4`. Typography does
+not change the color pairing; it makes the foreground easier to evaluate at
+common UI sizes and weights.
+
+## Neutral surfaces
+
+Neutral surfaces form the page, panel, and nested-container elevation ladder.
+Use the text tokens named for the selected surface whenever one exists.
+
+## Semantic surfaces
+
+Semantic surfaces support two deliberate foreground treatments.
+
+### Surface text
+
+The surface-text family keeps the semantic hue subtle and prioritizes strong
+readability.
+
+### Accent text
+
+The accent-text family preserves more semantic color. This is the pairing used
+by notification and Item card styles.
+
+## Solid accents and interaction states
+
+Solid accent fills are fixed brand colors with a dedicated light foreground.
+The numbered surface ramp represents default, hover, and pressed states and is
+shared by semantic themes.
+
+## Disabled states
+
+Disabled pairs intentionally have lower contrast than active content. Use the
+neutral pair for low-emphasis controls and the accent-disabled pair for muted
+solid semantic controls. Do not use disabled text for active information or
+content that must meet normal text contrast requirements.
+
+## Utility colors
+
+`#placeholder`, `#focus`, semantic accent icons, and `#overlay` have narrow
+roles. Keep them in those roles rather than treating them as general palette
+swatches.
+
+## Code syntax
+
+Syntax tokens are calibrated as a group against `#surface`. Use the semantic
+token for each syntax role instead of assigning arbitrary palette colors.
+
+## Borders and shadows
+
+Borders use the `1bw` design-system width. Shadow geometry comes from
+`src/tokens/shadows.ts`; the `#shadow-sm`, `#shadow-md`, and `#shadow-lg`
+colors adapt with the active scheme.
+
+## Scope
+
+This reference focuses on tokens intended for product UI. Internal loading-face
+colors and compatibility aliases are intentionally omitted.

package/docs/Typography.md

@@ -4,7 +4,7 @@ There are many ways to create typography elements like text labels and headings.
 
 ## Typography Components
 
-### Headings
+### Presets
 
 ### Paragraphs
 

package/docs/Usage.md

@@ -246,6 +246,16 @@ Largest line heights, designed for long-form content blocks.
 | `m2` | 16px | 28px | 400 |
 | `m3` | 14px | 24px | 400 |
 
+### Snippet / Monospace
+
+Sized to parallel `t2`–`t4`. Each preset sets `font-family` to `var(--font-mono)` (the design-system monospace stack from `Root`).
+
+| Preset | Size | Line Height | Weight | Notes |
+|--------|------|-------------|--------|-------|
+| `s2` | 16px | 22px | 400 | Larger code / snippet text |
+| `s3` | 14px | 20px | 400 | Default snippet size (matches Prism) |
+| `s4` | 12px | 18px | 400 | Compact code / snippet text |
+
 ### Special Presets
 
 | Preset | Description |

package/docs/components/content/CopySnippet.md

@@ -26,7 +26,7 @@ A code block with copy-to-clipboard functionality and syntax highlighting. Exten
 - `border` — `0`
 - `radius` — `1r`
 - `padding` — `0`
-- `preset` — `default`
+- `preset` — `default` (card chrome); code uses `s3`, or `t3` when `serif` is set
 
 ### Base Properties
 

package/docs/components/content/PrismCode.md

@@ -19,6 +19,7 @@ Syntax-highlighted code block using Prism. Supports multiple languages.
 - `padding` — `0`
 - `overflow` — `auto`
 - `scrollbar` — `styled`
+- `preset` — `s3` (monospace snippet size)
 
 ### Base Properties