@cube-dev/ui-kit 0.149.2 → 0.151.0

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
 

package/docs/components/other/CubeLogo.md

@@ -0,0 +1,58 @@
+# CubeLogo / CubeFullLogo
+
+The Cube brand marks. `CubeLogo` is the square cube mark; `CubeFullLogo` is the mark plus the wordmark on one canvas.
+
+Both are `Icon`-based, so they size and colour like any other icon: pass `size`, or let them inherit `font-size` and `currentColor` from their surroundings.
+
+## When to Use
+
+- `CubeLogo` — anywhere a compact brand mark fits: a collapsed sidebar, a favicon-sized slot, an avatar position, a loading state
+- `CubeFullLogo` — the header or sidebar of a full-width layout, an auth screen, an empty state, anywhere the wordmark should read
+
+These replace the removed `CloudLogo`, which baked in the previous brand artwork, hard-coded its hexes, and shipped the retired "Cube Cloud" wordmark.
+
+## Sizing
+
+`size` maps onto `font-size`, and the artwork is expressed in `em`:
+
+- **`CubeLogo`** is square — `size` sets both width and height.
+- **`CubeFullLogo`** takes `size` as its **height only**. The width follows the artwork's `98 / 28` ratio via `aspect-ratio`, so the wordmark is never squashed. Do not set an explicit `width` on it.
+
+```jsx
+<CubeLogo size="32px" />
+<CubeFullLogo size="24px" />   /* 24px tall, ~84px wide */
+```
+
+With no `size`, both fall back to `$icon-size` like every other icon, which makes them drop into text and button layouts without extra styling.
+
+## Colour
+
+Every path is drawn with `currentColor`. Inheriting is the default and usually correct:
+
+```jsx
+<Text color="#purple">
+  <CubeFullLogo />   {/* purple */}
+</Text>
+
+<CubeFullLogo color="#dark" />
+```
+
+There are **no baked-in brand hexes**, which is what lets the marks work on any surface and in any scheme.
+
+## Light and dark schemes
+
+The mark is two different drawings rather than one drawing recoloured — the dark variant is filled differently so it holds its weight against a dark surface. Both are rendered, and the `@dark` state swaps them in CSS.
+
+That means the swap costs no re-render, needs no scheme prop, and is correct during SSR and before hydration. It also means a snapshot of the DOM always contains both paths; assert on `[data-element="LightMark"]` / `[data-element="DarkMark"]` rather than on a single `path`.
+
+## Accessibility
+
+Both render `role="img"` with `aria-label="Cube"`, so they announce as an image with a name instead of being skipped or read as decorative.
+
+When the logo is itself the link home, put the name on the interactive element and let the logo stay decorative there — a nested duplicate name is worse than none:
+
+```jsx
+<Button aria-label="Cube home" to="/">
+  <CubeFullLogo aria-hidden />
+</Button>
+```