highsoft-ui 1.0.117 → 1.0.118

package/.cursorrules

@@ -0,0 +1,845 @@
+# Highsoft Design System — AI Guide
+
+This is the **highsoft-ui** component library and design token system for Highsoft products.
+
+## Quick setup
+
+```tsx
+import 'highsoft-ui/css'
+import 'highsoft-design-tokens/dist/css/tokens.css'
+
+import { Button, Heading, Typography, Link, Container } from 'highsoft-ui'
+```
+
+## Core rules
+
+1. **NEVER use hardcoded colors.** Always use semantic CSS custom properties (`--HS-*`).
+2. **NEVER use primitives in UI.** Primitives (`--primitives-*`) are only for token definitions — use semantic tokens so dark mode works automatically.
+3. **Always use the component library** when a component exists. Don't recreate buttons, inputs, headings, etc.
+4. **Use design token animations** for all transitions — never hardcode easing or durations.
+
+## Semantic color tokens
+
+Use these for all UI. They auto-switch between light and dark mode.
+
+### Backgrounds
+| Token | Use |
+|---|---|
+| `--HS-surface-ui-background-0` | Card/panel background (white in light) |
+| `--HS-surface-ui-background-50` | Subtle background (rows, hover states) |
+| `--HS-surface-ui-background-100` | Slightly darker background (code blocks) |
+| `--HS-common-background` | Page background |
+
+### Borders
+| Token | Use |
+|---|---|
+| `--HS-surface-ui-border-100` | Default border (cards, dividers) |
+| `--HS-surface-ui-border-200` | Stronger border (inputs, interactive) |
+| `--HS-surface-ui-border-300` | Emphasis border |
+
+### Text
+| Token | Use |
+|---|---|
+| `--HS-text-primary-default` | Headings, body text |
+| `--HS-text-secondary-default` | Subtitles, descriptions |
+| `--HS-text-tertiary-default` | Captions, hints, muted text |
+| `--HS-text-brand-default-alt` | Links, accents, interactive |
+
+### Brand surfaces
+| Token | Use |
+|---|---|
+| `--HS-surface-brand-background-50` | Subtle brand tint (badges, tags) |
+| `--HS-surface-brand-background-100` | Brand background (selected state) |
+| `--HS-surface-brand-border-200` | Brand border |
+
+### Status colors
+Each status (success, danger, attention) has: `background`, `background-boxed`, `border`, `border-boxed` for surfaces, and text tokens like `--HS-text-success-Primary`, `--HS-text-danger-default`, `--HS-text-attention-default`.
+
+## Animation tokens
+
+Never hardcode transitions. Use these CSS custom properties:
+
+```css
+/* Bounce — for interactive elements (buttons, toggles, inputs) */
+--animations-bounce-instant: 0.1s cubic-bezier(0.6, 1, 0.2, 1.2);
+--animations-bounce-fast:    0.2s cubic-bezier(0.6, 1, 0.2, 1.2);
+--animations-bounce-default: 0.3s cubic-bezier(0.6, 1, 0.2, 1.2);
+--animations-bounce-slow:    0.4s cubic-bezier(0.6, 1, 0.2, 1.2);
+
+/* Fade — for color changes, opacity, border transitions */
+--animations-fade-instant: 0.1s cubic-bezier(0.85, 0, 0.15, 1);
+--animations-fade-fast:    0.2s cubic-bezier(0.85, 0, 0.15, 1);
+--animations-fade-default: 0.3s cubic-bezier(0.85, 0, 0.15, 1);
+
+/* Classic — general purpose */
+--animations-classic-default: 0.3s cubic-bezier(0.65, 0, 0.35, 1);
+```
+
+Example:
+```css
+transition: border-color var(--animations-fade-fast),
+            box-shadow var(--animations-bounce-default);
+```
+
+## Shadow tokens
+
+```css
+--shadow-size-50   /* Subtle */
+--shadow-size-100  /* Cards */
+--shadow-size-200  /* Elevated (dropdowns, popovers) */
+--shadow-size-300  /* Modals */
+```
+
+## Typography tokens
+
+```css
+--typography-font-family          /* IBM Plex Sans Variable */
+--typography-size-75              /* 0.75rem — caption */
+--typography-size-100             /* 0.875rem — small body */
+--typography-size-200             /* 1rem — body */
+--typography-size-300             /* 1.125rem — large body */
+--typography-weight-normal: 400;
+--typography-weight-medium: 500;
+--typography-weight-semi: 600;
+--typography-lineHeight-ui: 100%;
+--typography-lineHeight-text: 130%;
+```
+
+## Components
+
+### Box
+The foundational layout component. Use it instead of raw `<div>` with inline styles.
+
+```tsx
+// Default card (background 0, border, radius 8, padding 24px)
+<Box>
+  <Heading level={4}>Title</Heading>
+  <Typography size={200}>Content</Typography>
+</Box>
+
+// Larger card
+<Box padding={700}>
+  Padding 32px
+</Box>
+
+// Subtle row
+<Box background={50} padding={400}>
+  Row content
+</Box>
+
+// Interactive card with hover effect
+<Box padding={700} radius={16} shadow={100} hoverable>
+  Hover me
+</Box>
+
+// Flex column with gap
+<Box gap={700}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+</Box>
+
+// No border, darker background
+<Box border={false} background={100} padding={500}>
+  Muted section
+</Box>
+
+// Polymorphic — render as <section>, <a>, etc.
+<Box as="section" background={100} padding={900}>
+  Full-width section
+</Box>
+```
+
+- **`background`:** `0` (card/white, default), `50` (subtle), `100` (darker)
+- **`border`:** `true` (default), `200`, `300` for stronger, `false` to disable
+- **`radius`:** `0`, `4`, `8` (default), `16`, `32`
+- **`padding`:** `0`, `100`–`1000` (maps to `--containers-inner-padding-*`). Default `600` (24px). Use `700` (32px) for larger cards
+- **`gap`:** `0`, `200`, `400`, `600`, `700`, `800`, `900`, `1000` (maps to `--item-spacing-*`, sets `display: flex; flex-direction: column`)
+- **`shadow`:** `50`, `100`, `200`, `300`
+- **`hoverable`:** adds animated border-highlight + shadow-lift on hover using `--animations-fade-fast` and `--animations-bounce-default`
+- **`as`:** polymorphic — render as any HTML element
+
+### Button
+```tsx
+<Button variant="brand" size={300}>Primary action</Button>
+<Button variant="neutral" size={200}>Secondary</Button>
+<Button variant="soft" size={200}>Soft</Button>
+<Button variant="transparent" size={200}>Ghost</Button>
+<Button variant="danger" size={200}>Destructive</Button>
+
+// With icons (from @untitled-ui/icons-react)
+<Button variant="brand" iconLeft={<Plus />}>Create</Button>
+<Button variant="neutral" iconRight={<ArrowRight />}>Continue</Button>
+<Button variant="soft" iconLeft={<Copy06 />} iconRight={<Check />}>Both sides</Button>
+```
+- **Variants:** `brand`, `neutral`, `soft`, `transparent`, `plain`, `success`, `attention`, `danger`
+- **Sizes:** `50`, `100`, `200`, `300`, `400`, `500`
+- **`iconLeft`:** `ReactNode` — icon placed before the label
+- **`iconRight`:** `ReactNode` — icon placed after the label
+- **`as`:** polymorphic — auto-detects `<a>` when `href` is provided
+
+### Heading
+```tsx
+<Heading level={1}>Page title</Heading>
+<Heading level={2}>Section title</Heading>
+<Heading level={4}>Card title</Heading>
+```
+- **Levels:** `1`–`6`
+
+### Typography
+```tsx
+<Typography size={200}>Body text</Typography>
+<Typography size={75} style={{ color: 'var(--HS-text-tertiary-default)' }}>Caption</Typography>
+<Typography size={300} weight="semi">Large semi-bold</Typography>
+```
+- **Sizes:** `50`, `75`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`
+- **Weights:** `"normal"`, `"medium"`, `"semi"`
+
+### Link
+```tsx
+<Link href="/page">Default link</Link>
+<Link href="/page" variant="fancy">Animated link</Link>
+```
+- **Variants:** `native` (subtle underline, default), `fancy` (animated slide-in underline)
+- Polymorphic: `<Link as={RouterLink} to="/page">` for SPA navigation
+
+### Icon
+```tsx
+<Icon name="chevron-right" size={200} />
+```
+
+### InputSolo
+```tsx
+<InputSolo label="Email" placeholder="you@example.com" />
+```
+
+### InputGrouped / SelectGrouped / FormGroup / FormRow
+```tsx
+<FormGroup>
+  <FormRow>
+    <InputGrouped label="First name" />
+    <InputGrouped label="Last name" />
+  </FormRow>
+  <SelectGrouped label="Country" options={[...]} />
+</FormGroup>
+```
+
+### Label (formerly NewTag)
+```tsx
+<Label variant="brand">New</Label>                                // Default with Stars02 icon
+<Label variant="success" iconLeft={false}>Live</Label>            // No icon
+<Label variant="attention" iconLeft={<MyIcon />}>Warning</Label>  // Custom icon
+<Label variant="neutral" iconLeft={false}>v12.1</Label>           // Plain text label
+<Label variant="danger" border>Breaking</Label>                   // With border
+```
+- **Variants:** `success` (default), `brand`, `attention`, `danger`, `neutral`
+- **`iconLeft`:** `true` (Stars02, default), `false` (none), or any `ReactNode` — aligned with Button's `iconLeft` pattern
+- **`icon`:** deprecated alias for `iconLeft` — still works but use `iconLeft` in new code
+- **`border`:** adds a visible border
+- **`children`:** custom text (defaults to "New")
+- `NewTag` is a deprecated alias — use `Label` in new code
+
+### CopyCode
+Pill-shaped inline code display with integrated copy button and success state.
+```tsx
+<CopyCode>npm i highsoft-ui highsoft-design-tokens</CopyCode>
+<CopyCode label="Copy" copiedLabel="Copied" duration={2000}>yarn add highsoft-ui</CopyCode>
+```
+- Uses `Button` (soft → success variant) with `Copy06` / `Check` icons internally
+- **`children`:** `string` — the code text to display and copy
+- **`duration`:** ms for success state (default: 2000)
+
+### Layout
+```tsx
+<Header />
+<SubHeader />
+<Container>{children}</Container>
+<Footer />
+```
+
+### Notification
+```tsx
+<Notification variant="success" title="Saved" />
+<Notification variant="danger" title="Error" message="Something went wrong" />
+```
+
+## Hooks
+
+### useSuccessFlash
+Triggers a temporary success state for any component. Use with Button variant switching for click confirmations (copy, save, submit, etc.).
+
+```tsx
+import { useSuccessFlash } from 'highsoft-ui'
+
+const [flash, flashing] = useSuccessFlash()    // default 2s
+const [flash, flashing] = useSuccessFlash(3000) // custom duration
+
+<Button
+  variant={flashing ? 'success' : 'neutral'}
+  onClick={() => { doSomething(); flash(); }}
+>
+  {flashing ? 'Done!' : 'Save'}
+</Button>
+```
+
+### useClipboard
+Copy text to clipboard with a built-in success state.
+
+```tsx
+import { useClipboard } from 'highsoft-ui'
+
+const [copy, copied] = useClipboard()
+
+<Button
+  variant={copied ? 'success' : 'neutral'}
+  onClick={() => copy('some text')}
+>
+  {copied ? 'Copied!' : 'Copy'}
+</Button>
+```
+
+### Combining both for copy buttons
+```tsx
+const [copy, copied] = useClipboard()
+const [flash, flashing] = useSuccessFlash()
+const active = copied || flashing
+
+<button onClick={() => { copy(text); flash(); }}>
+  {active ? '✓ Copied!' : 'Copy'}
+</button>
+```
+
+## Link mixin (SCSS only, no React)
+
+For projects using only design tokens without the React library:
+
+```scss
+@use 'highsoft-design-tokens/dist/scss/mixins/links' as *;
+
+a       { @include link; }          // native — subtle underline
+a.fancy { @include link(fancy); }   // animated slide-in underline
+```
+
+## Building custom UI
+
+Use the `<Box>` component for all layout containers. Prefer `<Box>` over raw `<div>` with inline styles.
+
+### Card
+```tsx
+<Box background={0} border padding={700} radius={16}>
+  <Heading level={4}>Title</Heading>
+  <Typography size={200} style={{ color: 'var(--HS-text-secondary-default)' }}>
+    Description text
+  </Typography>
+</Box>
+```
+
+### Row / list item
+```tsx
+<Box background={50} border padding={400} radius={8} style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+  {/* content */}
+</Box>
+```
+
+### Interactive card
+```tsx
+<Box background={0} border padding={700} radius={16} shadow={100} hoverable>
+  Hover lifts and highlights automatically
+</Box>
+```
+
+### Stacked layout with gap
+```tsx
+<Box background={0} border padding={700} radius={16} gap={700}>
+  <Heading level={4}>Section</Heading>
+  <Typography size={200}>Spaced with design token gap</Typography>
+  <Button variant="brand" size={300}>Action</Button>
+</Box>
+```
+
+### Badge / tag pattern
+```tsx
+<span style={{
+  display: 'inline-flex',
+  padding: '4px 10px',
+  borderRadius: 20,
+  fontSize: 11,
+  fontWeight: 600,
+  background: 'var(--HS-surface-brand-background-50)',
+  color: 'var(--HS-text-brand-default-alt)',
+  border: '1px solid var(--HS-surface-brand-border-200)',
+}}>
+  Label
+</span>
+```
+
+## Dark mode
+
+Dark mode is automatic when using semantic tokens. Toggle with:
+```html
+<html data-theme="dark">
+```
+No code changes needed — all `--HS-*` tokens remap automatically.
+
+## Icon library
+
+All icons come from **`@untitled-ui/icons-react`** (Untitled UI icon set). Never use emoji, ASCII characters (✓, ✗, →), or other icon libraries.
+
+```tsx
+import { Plus, ArrowRight, Check, Copy06, Trash01, Settings04, Star01, Share07, Download01, Send01 } from '@untitled-ui/icons-react'
+```
+
+Icons auto-size inside Button and Label based on their `size` prop:
+| Button size | Icon size |
+|---|---|
+| `50` | 12×12 |
+| `100` | 12×12 |
+| `200` | 16×16 |
+| `300` | 16×16 |
+| `400` | 20×20 |
+| `500` | 24×24 |
+
+### Icon prop pattern (consistent across components)
+
+All components use the same `iconLeft` / `iconRight` naming:
+
+```tsx
+// Button — ReactNode | undefined
+<Button iconLeft={<Plus />}>Create</Button>
+<Button iconRight={<ArrowRight />}>Next</Button>
+<Button iconLeft={<Copy06 />} iconRight={<Check />}>Both</Button>
+
+// Label — boolean | ReactNode (true = default Stars02 icon)
+<Label iconLeft={true}>New</Label>           // Stars02 (default)
+<Label iconLeft={false}>v12.1</Label>        // no icon
+<Label iconLeft={<Check />}>Passed</Label>   // custom icon
+
+// CopyCode — icons handled internally (Copy06 → Check on success)
+<CopyCode>npm i highsoft-ui</CopyCode>
+```
+
+## Component Do's and Don'ts
+
+### Button
+- **Do** use `brand` for the single primary action per section
+- **Don't** use multiple `brand` buttons side by side — use `neutral` or `soft` for secondary
+- **Do** keep grouped buttons at the same `size`
+- **Don't** mix sizes like `size={300}` next to `size={100}`
+- **Do** use `iconLeft`/`iconRight` on standard-width buttons
+- **Don't** add icons to `fullWidth` buttons — the wide gap looks disconnected
+- **Do** use `href` for navigation so it renders as `<a>` (a11y, cmd-click, right-click)
+- **Don't** use `<button>` with `onClick` + router.push for navigation
+- **Do** use `useSuccessFlash` with `iconLeft={<Check />}` for success states
+- **Don't** use ASCII characters like ✓ or ✗ — always use icon components
+- **Do** use `danger` only for destructive actions (delete, remove, revoke)
+- **Don't** use `danger` for "Cancel" or "Go back" — use `neutral` or `transparent`
+
+### Label
+- **Do** use `iconLeft={false}` for plain text labels like version numbers
+- **Don't** use Label for long text — it's designed for short status/category tags
+
+## WordPress blocks team guide
+
+This section is for the team building WordPress Gutenberg blocks that match the Highsoft design system.
+
+Gutenberg blocks use React, so there are **two contexts** with different approaches:
+
+| Context | Technology | Approach |
+|---|---|---|
+| **Block editor** (`edit.js`) | React | Import and use `highsoft-ui` components directly |
+| **Frontend output** (`save.js` / PHP render) | Static HTML | Use design token CSS custom properties with matching class names |
+
+### Block editor — use the React components directly
+
+The block editor is React. Import components from `highsoft-ui` and map block attributes to props:
+
+```tsx
+// edit.js — the editor preview uses real components
+import 'highsoft-ui/css'
+import 'highsoft-design-tokens/dist/css/tokens.css'
+import { Button, Label, Heading, Typography, Box } from 'highsoft-ui'
+
+export default function Edit({ attributes, setAttributes }) {
+  const { variant, size, label, href, iconName } = attributes
+
+  return (
+    <Box padding={700} radius={16}>
+      <Heading level={4}>{attributes.title}</Heading>
+      <Typography size={200} style={{ color: 'var(--HS-text-secondary-default)' }}>
+        {attributes.description}
+      </Typography>
+      <div style={{ display: 'flex', gap: 12, alignItems: 'center', marginTop: 16 }}>
+        <Button variant={variant} size={size} href={href}>
+          {label}
+        </Button>
+        <Label variant="brand" iconLeft={false}>Recommended</Label>
+      </div>
+    </Box>
+  )
+}
+```
+
+```js
+// block.json — map attributes to component props
+{
+  "attributes": {
+    "variant": { "type": "string", "default": "brand" },
+    "size":    { "type": "number", "default": 300 },
+    "label":   { "type": "string", "default": "Get started" },
+    "href":    { "type": "string" }
+  }
+}
+```
+
+**Block attribute names should match component prop names** (`variant`, `size`, `iconLeft`, `fullWidth`, etc.) so the mapping is 1:1.
+
+### Frontend output — use PHP dynamic render (recommended)
+
+Use **`render.php`** instead of `save.js` for frontend output. The block stores only attributes (JSON), and PHP renders the HTML on every page load. This gives total control — update the template once and every block instance updates automatically, with no deprecation migrations.
+
+```json
+// block.json — use render instead of save
+{
+  "apiVersion": 3,
+  "name": "hs/button",
+  "title": "HS Button",
+  "render": "file:./render.php",
+  "attributes": {
+    "variant": { "type": "string", "default": "brand" },
+    "size":    { "type": "number", "default": 300 },
+    "label":   { "type": "string", "default": "Get started" },
+    "href":    { "type": "string" },
+    "iconLeft": { "type": "string" }
+  }
+}
+```
+
+```php
+<?php
+// render.php — generates the frontend HTML from attributes
+$variant = $attributes['variant'] ?? 'brand';
+$size    = $attributes['size'] ?? 300;
+$label   = $attributes['label'] ?? 'Get started';
+$href    = $attributes['href'] ?? '#';
+$icon    = $attributes['iconLeft'] ?? '';
+
+$classes = "hs-button hs-button--{$variant} hs-button--{$size}";
+?>
+<a class="<?php echo esc_attr($classes); ?>" href="<?php echo esc_url($href); ?>">
+  <?php if ($icon) : ?>
+    <?php echo hs_get_icon_svg($icon, $size); // helper that returns inline SVG ?>
+  <?php endif; ?>
+  <span><?php echo esc_html($label); ?></span>
+</a>
+```
+
+```js
+// save.js — returns null for dynamic blocks
+export default function Save() {
+  return null;
+}
+```
+
+**Why `render.php` over `save.js`:**
+- Change a border-radius or token → every block updates instantly
+- No "This block contains unexpected content" errors when evolving the design
+- HTML stays in sync with the component library — single source of truth
+- Full server-side control (conditional logic, user roles, A/B testing)
+
+### Frontend CSS — style the PHP output with tokens
+
+```php
+// Enqueue the token CSS in your block or theme
+wp_enqueue_style('hs-tokens', 'path/to/highsoft-design-tokens/dist/css/tokens.css');
+```
+
+#### Button styles
+```css
+/* style.css — frontend styles using the same tokens as the React components */
+.hs-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  border: 1px solid transparent;
+  cursor: pointer;
+  white-space: nowrap;
+  text-decoration: none;
+  font-family: var(--typography-font-family);
+  transition: transform 0.2s cubic-bezier(0.075, 0.82, 0.165, 1);
+}
+
+/* Size 200 (default) */
+.hs-button--200 {
+  height: 32px;
+  padding: 0 7px;
+  border-radius: 8px;
+  font-size: var(--typography-size-100);
+  font-weight: var(--typography-weight-medium);
+  gap: 8px;
+}
+.hs-button--200 svg { width: 16px; height: 16px; }
+
+/* Size 300 */
+.hs-button--300 {
+  height: 36px;
+  padding: 0 9px;
+  border-radius: 8px;
+  font-size: var(--typography-size-200);
+  font-weight: var(--typography-weight-medium);
+  gap: 10px;
+}
+.hs-button--300 svg { width: 16px; height: 16px; }
+
+/* Variants — use button token CSS custom properties */
+.hs-button--brand {
+  background: var(--button-colors-brand-background-default);
+  color: var(--button-colors-brand-text-default);
+  border-color: var(--button-colors-brand-stroke-outer-default);
+}
+.hs-button--brand:hover {
+  background: var(--button-colors-brand-background-hover);
+}
+.hs-button--neutral {
+  background: var(--button-colors-neutral-background-default);
+  color: var(--button-colors-neutral-text-default);
+  border-color: var(--button-colors-neutral-stroke-outer-default);
+}
+.hs-button--soft {
+  background: var(--button-colors-soft-background-default);
+  color: var(--button-colors-soft-text-default);
+  border-color: var(--button-colors-soft-stroke-outer-default);
+}
+```
+
+#### Label styles
+```css
+.hs-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  height: 18px;
+  padding: 0 6px;
+  border-radius: 4px;
+  font-size: 0.75rem;
+  font-weight: var(--typography-weight-medium);
+  text-transform: uppercase;
+}
+.hs-label svg { width: 12px; height: 12px; }
+.hs-label--with-icon { height: 24px; padding: 0 9px; border-radius: 6px; }
+
+/* Variants — use tag token CSS custom properties */
+.hs-label--brand     { background: var(--tags-brand-background);     color: var(--tags-brand-text); }
+.hs-label--success   { background: var(--tags-success-background);   color: var(--tags-success-text); }
+.hs-label--attention { background: var(--tags-attention-background); color: var(--tags-attention-text); }
+.hs-label--danger    { background: var(--tags-danger-background);    color: var(--tags-danger-text); }
+.hs-label--neutral   { background: var(--tags-neutral-background);   color: var(--tags-neutral-text); }
+```
+
+#### Link styles (SCSS mixin)
+```scss
+@use 'highsoft-design-tokens/dist/scss/mixins/links' as *;
+
+.hs-link         { @include link; }          // native — subtle underline
+.hs-link--fancy  { @include link(fancy); }   // animated slide-in underline
+```
+
+### Token naming conventions for blocks
+
+Use the `hs-` prefix and mirror the React component API:
+
+| React prop | Block attribute | CSS class | Example |
+|---|---|---|---|
+| `variant="brand"` | `variant: "brand"` | `hs-{component}--brand` | `hs-button--brand` |
+| `size={300}` | `size: 300` | `hs-{component}--300` | `hs-button--300` |
+| `iconLeft={<X />}` | `iconLeft: "x"` | `hs-{component}--with-icon` | `hs-label--with-icon` |
+| `fullWidth` | `fullWidth: true` | `hs-{component}--full` | `hs-button--full` |
+| `border` | `border: true` | `hs-{component}--border` | `hs-label--border` |
+
+### Dark mode in WordPress
+
+Add `data-theme="dark"` to the `<html>` element. All `--HS-*` tokens remap automatically — no additional CSS needed.
+
+```php
+<html data-theme="<?php echo get_theme_mod('hs_dark_mode') ? 'dark' : 'light'; ?>">
+```
+
+### Common block patterns (frontend CSS)
+
+#### Pricing card
+```css
+.wp-block-hs-pricing {
+  background: var(--HS-surface-ui-background-0);
+  border: 1px solid var(--HS-surface-ui-border-100);
+  border-radius: 16px;
+  padding: 32px;
+}
+.wp-block-hs-pricing__title {
+  color: var(--HS-text-primary-default);
+  font-family: var(--typography-font-family);
+  font-size: var(--typography-size-300);
+  font-weight: var(--typography-weight-semi);
+}
+.wp-block-hs-pricing__description {
+  color: var(--HS-text-secondary-default);
+  font-size: var(--typography-size-200);
+  line-height: var(--typography-lineHeight-text);
+}
+```
+
+#### Feature grid item with hover
+```css
+.wp-block-hs-feature {
+  background: var(--HS-surface-ui-background-0);
+  border: 1px solid var(--HS-surface-ui-border-100);
+  border-radius: 8px;
+  padding: 24px;
+  transition: border-color var(--animations-fade-fast),
+              box-shadow var(--animations-bounce-default);
+}
+.wp-block-hs-feature:hover {
+  border-color: var(--HS-surface-brand-border-200);
+  box-shadow: var(--shadow-size-100);
+}
+```
+
+### Block development rules
+
+1. **Use the React components in `edit.js`** — import from `highsoft-ui` directly, don't rebuild components
+2. **Use `render.php` for frontend output** — dynamic blocks store only attributes, PHP renders the HTML. No `save.js` needed (return `null`)
+3. **Name block attributes after component props** — `variant`, `size`, `iconLeft`, `fullWidth` — so the editor↔frontend mapping is obvious
+4. **Always use token CSS custom properties** — never hardcode colors, shadows, radii, or animation values
+5. **Icons must be inline SVGs** on the frontend — copy the SVG source from `@untitled-ui/icons-react`. In the editor, use the React icon components directly
+6. **Use `box-sizing: border-box`** on all interactive elements to prevent height mismatches
+7. **Test in both light and dark mode** — if you only use `--HS-*` tokens, dark mode works automatically
+8. **Use the SCSS link mixin** for all anchor styling — don't write custom link hover/underline CSS
+
+## Headless CMS / static site guide
+
+If the site uses a **headless CMS** (git-based, API-based, or any visual editor) with a React or Astro frontend, the components can be used **directly** — no CSS recreation needed. This is the preferred approach when developers control the frontend and a non-technical editor only needs to change content.
+
+### Architecture
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌───────────────┐
+│  CMS / Editor   │────▶│  Content API │────▶│  React / Astro │
+│  (visual editor │     │  or JSON/MD  │     │  uses highsoft-ui│
+│   for content)  │     │  files       │     │  components     │
+└─────────────────┘     └──────────────┘     └───────────────┘
+```
+
+The CMS manages **content** (text, images, links). The frontend uses the **real components** from `highsoft-ui`. Design tokens, variants, sizes — all handled by the component library. One implementation, not two.
+
+### Content schema → component props
+
+Define content fields that map directly to component props. Keep the CMS schema minimal — only expose what the editor needs to change:
+
+```ts
+// Example: a CTA block schema
+interface CTABlock {
+  // Editor-controlled content
+  title: string
+  description: string
+  buttonLabel: string
+  buttonHref: string
+  // Design props (can be editor-controlled or hardcoded per template)
+  buttonVariant?: 'brand' | 'neutral' | 'soft'   // default: 'brand'
+  buttonSize?: 200 | 300 | 400                     // default: 300
+}
+```
+
+```tsx
+// The component uses highsoft-ui directly — no CSS duplication
+import { Button, Heading, Typography, Box } from 'highsoft-ui'
+
+export function CTABlock({ title, description, buttonLabel, buttonHref, buttonVariant = 'brand', buttonSize = 300 }: CTABlock) {
+  return (
+    <Box padding={700} radius={16}>
+      <Heading level={3}>{title}</Heading>
+      <Typography size={200} style={{ color: 'var(--HS-text-secondary-default)' }}>
+        {description}
+      </Typography>
+      <Button variant={buttonVariant} size={buttonSize} href={buttonHref}>
+        {buttonLabel}
+      </Button>
+    </Box>
+  )
+}
+```
+
+### Page templates with editable regions
+
+For mostly-static pages, define templates where only the content is CMS-editable. The layout and design stay in code:
+
+```tsx
+// A page template — layout is code, content comes from CMS
+import { Button, Heading, Typography, Box, Label, CopyCode } from 'highsoft-ui'
+
+interface PricingPageContent {
+  hero: { title: string; subtitle: string }
+  plans: Array<{
+    name: string
+    price: string
+    description: string
+    features: string[]
+    cta: string
+    href: string
+    recommended?: boolean
+  }>
+}
+
+export function PricingPage({ content }: { content: PricingPageContent }) {
+  return (
+    <>
+      <Heading level={1}>{content.hero.title}</Heading>
+      <Typography size={300} style={{ color: 'var(--HS-text-secondary-default)' }}>
+        {content.hero.subtitle}
+      </Typography>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 24 }}>
+        {content.plans.map((plan) => (
+          <Box key={plan.name} padding={700} radius={16} shadow={plan.recommended ? 100 : undefined} hoverable>
+            {plan.recommended && <Label variant="brand" iconLeft={false}>Recommended</Label>}
+            <Heading level={3}>{plan.name}</Heading>
+            <Heading level={2}>{plan.price}</Heading>
+            <Typography size={200}>{plan.description}</Typography>
+            <Button variant={plan.recommended ? 'brand' : 'neutral'} size={300} href={plan.href} fullWidth>
+              {plan.cta}
+            </Button>
+          </Box>
+        ))}
+      </div>
+    </>
+  )
+}
+```
+
+### What goes in the CMS vs. what stays in code
+
+| In the CMS (editor can change) | In code (developer controls) |
+|---|---|
+| Page titles, headings, body text | Component selection and layout |
+| Button labels and link URLs | Variant, size, design props |
+| Image URLs and alt text | Spacing, grid structure |
+| Feature lists, pricing data | Animation tokens, hover states |
+| Meta descriptions, SEO fields | Dark mode, responsive breakpoints |
+
+The editor should never need to pick a `variant` or `size` — those are design decisions that belong in the template. Only expose design props to the CMS when there's a genuine editorial need (e.g. "highlighted" toggle on a pricing card).
+
+### Why this approach works
+
+- **One implementation** — the real React components, not a CSS recreation
+- **Design updates propagate instantly** — change a token or component prop, rebuild, done
+- **Editor gets a simple interface** — text fields and toggles, not CSS classes
+- **Type safety** — content schema is TypeScript, caught at build time
+- **Static output** — pages pre-render to HTML at build time, no runtime cost
+- **Dark mode works automatically** — components use semantic tokens
+
+## File structure
+
+```
+lib/
+  components/     — React components (Button, Heading, Typography, Link, Label, Box, CopyCode, etc.)
+  scss/           — SCSS variables and semantic token definitions
+  utils.ts        — Shared hooks (useSuccessFlash, useClipboard, useTheme)
+  main.ts         — Package entry point and exports
+stories/          — Storybook documentation pages
+```