@beehexa/design-rules 0.0.0-stage → 2611.3.2

package/dist/docs/src/components/logos/LogoMisuse.astro

@@ -0,0 +1,96 @@
+---
+// Do and don't. Each example is the real logo with one thing done wrong.
+// The six don'ts of the 2025 brand guide (p22), plus effects and low-contrast backgrounds.
+import { COLORS, ICON_H, ICON_PATH, ICON_SCALE, ICON_TOP, WORDMARKS } from '../../lib/logo-geometry';
+import { langOf } from '../../lib/i18n';
+import LogoSvg from './LogoSvg.astro';
+import Fig from './Fig.astro';
+import '../../styles/logos.css';
+
+const lang = langOf(Astro.url.pathname);
+const iconPx = 36;
+const s = iconPx / ICON_H;
+// "Don't retype the name": the icon with the name set in a serif typeface.
+const serif = [WORDMARKS.beehexa].map((word) => {
+  const m = 1 / s; // the same 1 px margin as LogoSvg
+  const w = Math.ceil((word.width + 2 * m) * s - 1e-6);
+  const h = Math.ceil((ICON_H + 2 * m) * s - 1e-6);
+  return { w, h, x: word.x, viewBox: `${-m} ${ICON_TOP - m} ${w / s} ${h / s}` };
+});
+const cross = '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="currentColor"/><path d="M5.5 5.5l5 5m0-5l-5 5" stroke="#fff" stroke-width="1.6" stroke-linecap="round"/></svg>';
+const check = '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="currentColor"/><path d="M4.8 8.2l2.1 2.1 4.3-4.6" stroke="#fff" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+
+type Case = { key: string; title: string; text: string; alt: string };
+const C: Record<string, Case> = Object.fromEntries(
+  (lang === 'vi'
+    ? [
+        ['do', 'Nên', 'Dùng file gốc đúng như đã vẽ, trên nền mà phiên bản đó dành cho.', 'Đúng: lockup như bản vẽ'],
+        ['stretch', 'Không kéo giãn hay ép dẹt', 'Chỉ phóng to, thu nhỏ theo đúng tỉ lệ.', 'Sai: bị kéo giãn'],
+        ['recolour', 'Không đổi màu', 'Chỉ dùng một trong bốn bản màu.', 'Sai: bị đổi màu'],
+        ['serif', 'Không gõ lại tên', 'Không tự gõ wordmark bằng font, kiểu chữ hay cách viết hoa khác.', 'Sai: tên gõ bằng font khác'],
+        ['fade', 'Không làm mờ', 'Luôn để logo ở độ đậm đặc 100%.', 'Sai: bị làm mờ'],
+        ['rotate', 'Không xoay', 'Logo luôn nằm ngang.', 'Sai: bị xoay'],
+        ['swap', 'Không đổi bố cục', 'Icon trước, chữ sau, đúng khoảng cách đã vẽ. Không có bản xếp dọc.', 'Sai: chữ đứng trước icon'],
+        ['effects', 'Không thêm hiệu ứng', 'Không đổ bóng, viền, phát sáng, chuyển màu hay 3D.', 'Sai: thêm đổ bóng'],
+        ['contrast', 'Không đặt trên nền thiếu tương phản', 'Trên nền vàng hoặc nền rối, dùng bản xám ghi hoặc bản trắng.', 'Sai: logo màu trên nền vàng'],
+      ]
+    : [
+        ['do', 'Do', 'Use the master file as drawn, on a background its version was made for.', 'Correct: the lockup as drawn'],
+        ['stretch', 'Don’t stretch or squash', 'Scale it in proportion only.', 'Wrong: stretched'],
+        ['recolour', 'Don’t recolour', 'Use one of the four colour versions.', 'Wrong: recoloured'],
+        ['serif', 'Don’t retype the name', 'Never set the wordmark in a font, case or style of your own.', 'Wrong: name set in another typeface'],
+        ['fade', 'Don’t fade it', 'Keep the logo at full opacity.', 'Wrong: faded'],
+        ['rotate', 'Don’t rotate', 'The logo always sits level.', 'Wrong: rotated'],
+        ['swap', 'Don’t rearrange', 'Icon first, then the wordmark, at the spacing drawn. No stacked version.', 'Wrong: wordmark before the icon'],
+        ['effects', 'Don’t add effects', 'No shadows, outlines, glows, gradients or 3D.', 'Wrong: drop shadow added'],
+        ['contrast', 'Don’t lose the contrast', 'On yellow or busy backgrounds, use the graphite or white version.', 'Wrong: colour logo on a yellow background'],
+      ]
+  ).map(([key, title, text, alt]) => [key, { key, title, text, alt }]),
+);
+---
+
+<div class="logo-cards misuse" style="--cols:3">
+  <div class="logo-card is-do">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" label={C.do.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-do" set:html={check + C.do.title} /><p>{C.do.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" style="transform:scale(1.4,0.8)" label={C.stretch.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.stretch.title} /><p>{C.stretch.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" fills={['#7c3aed', '#7c3aed']} label={C.recolour.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.recolour.title} /><p>{C.recolour.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage">
+      {serif.map((d) => (
+        <Fig id="misuse-serif" class={['px-center']} viewBox={d.viewBox} w={d.w} h={d.h} label={C.serif.alt}>
+          <path fill={COLORS.yellow} fill-rule="evenodd" transform={`translate(0 ${ICON_TOP}) scale(${ICON_SCALE})`} d={ICON_PATH} />
+          <text x={d.x} y="0" fill={COLORS.graphite} font-family="Georgia, 'Times New Roman', serif" font-size="1900" font-style="italic">Beehexa</text>
+        </Fig>
+      ))}
+    </div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.serif.title} /><p>{C.serif.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" style="opacity:.35" label={C.fade.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.fade.title} /><p>{C.fade.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" style="transform:rotate(-12deg)" label={C.rotate.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.rotate.title} /><p>{C.rotate.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" swap label={C.swap.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.swap.title} /><p>{C.swap.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-white misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" style="filter:drop-shadow(3px 4px 3px rgb(0 0 0 / 45%))" label={C.effects.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.effects.title} /><p>{C.effects.text}</p></div>
+  </div>
+  <div class="logo-card is-dont">
+    <div class="logo-stage bg-yellow misuse-stage"><LogoSvg iconPx={iconPx} class="px-center" label={C.contrast.alt} /></div>
+    <div class="logo-card-body"><p class="verdict verdict-dont" set:html={cross + C.contrast.title} /><p>{C.contrast.text}</p></div>
+  </div>
+</div>

package/dist/docs/src/components/logos/LogoPair.astro

@@ -0,0 +1,26 @@
+---
+// One lockup on a light and a dark panel, centred on whole pixels.
+import LogoSvg from './LogoSvg.astro';
+import { langOf } from '../../lib/i18n';
+import '../../styles/logos.css';
+
+interface Props {
+  kind?: 'beehexa' | 'hexasync';
+  name: string;
+}
+const { kind = 'beehexa', name } = Astro.props;
+const lang = langOf(Astro.url.pathname);
+const light = lang === 'vi' ? `Logo ${name} cho nền sáng` : `${name} logo for light backgrounds`;
+const dark = lang === 'vi' ? `Logo ${name} cho nền tối` : `${name} logo for dark backgrounds`;
+---
+
+<div class="logo-hero-panels pair">
+  <div class="logo-stage hero-stage bg-white">
+    <LogoSvg kind={kind} version="light" iconPx={48} class="px-center hero-lg" label={light} />
+    <LogoSvg kind={kind} version="light" iconPx={28} class="px-center hero-sm" label={light} />
+  </div>
+  <div class="logo-stage hero-stage bg-graphite">
+    <LogoSvg kind={kind} version="dark" iconPx={48} class="px-center hero-lg" label={dark} />
+    <LogoSvg kind={kind} version="dark" iconPx={28} class="px-center hero-sm" label={dark} />
+  </div>
+</div>

package/dist/docs/src/components/logos/LogoSvg.astro

@@ -0,0 +1,68 @@
+---
+// The logo from the master geometry at a whole-pixel size, shown as a 3× PNG (see Fig.astro).
+// The box is rounded up to whole pixels by widening the viewBox, never by scaling the artwork,
+// so the icon keeps its exact height. Centre it with the `px-center` class (logos.css).
+import { COLORS, ICON_H, ICON_PATH, ICON_SCALE, ICON_TOP, ICON_W, WORDMARKS, type Version } from '../../lib/logo-geometry';
+import Fig from './Fig.astro';
+import '../../styles/logos.css';
+
+interface Props {
+  kind?: 'beehexa' | 'hexasync' | 'icon';
+  version?: Version | 'auto'; // auto: light on the light theme, dark on the dark theme
+  iconPx: number; // icon height in px
+  clear?: boolean; // include the clear space (1 x-height) around the logo
+  label?: string; // accessible name; empty = decorative
+  class?: string;
+  style?: string; // misuse demos: transforms and filters on the picture
+  swap?: boolean; // misuse demo: wordmark before the icon
+  fills?: [string, string]; // misuse demo: other colours for icon and text
+}
+
+const { kind = 'beehexa', version = 'light', iconPx, clear = false, label = '', class: cls, style = '', swap = false, fills: custom } = Astro.props;
+
+const fills: Record<Version, [string, string]> = {
+  light: [COLORS.yellow, COLORS.graphite],
+  dark: [COLORS.yellow, COLORS.white],
+  white: [COLORS.white, COLORS.white],
+  graphite: [COLORS.graphite, COLORS.graphite],
+};
+const s = iconPx / ICON_H;
+const CLEAR = 1056;
+
+const figs = (() => {
+  const word = kind === 'icon' ? undefined : WORDMARKS[kind];
+  const inkW = word ? word.width : ICON_W;
+  const inkH = word ? word.height : ICON_H;
+  // Without the clear space, keep a 1 px margin: a picture cropped to the ink loses the soft
+  // edge of the icon's points and the descender of the "y" in HexaSync.
+  const pad = clear ? CLEAR : 1 / s;
+  const w = Math.ceil((inkW + 2 * pad) * s - 1e-6);
+  const h = Math.ceil((inkH + 2 * pad) * s - 1e-6);
+  const viewBox = `${-pad} ${ICON_TOP - pad} ${w / s} ${h / s}`;
+  // Misuse demo only: put the wordmark first, then the icon.
+  const wordX = swap && word ? 0 : word?.x;
+  const iconX = swap && word ? word.width - ICON_W : 0;
+  const versions = version === 'auto' ? (['light', 'dark'] as const) : [version];
+  return versions.map((v) => {
+    const [iconFill, wordFill] = custom ?? fills[v];
+    const extra = [clear && 'clear', swap && 'swap', custom && custom.join('').replace(/#/g, '')].filter(Boolean).join('-');
+    const figId = [kind, v, iconPx, extra].filter(Boolean).join('-');
+    return { v, w, h, viewBox, wordX, iconX, word, iconFill, wordFill, figId };
+  });
+})();
+---
+
+{figs.map((f) => (
+  <Fig
+    id={f.figId}
+    w={f.w}
+    h={f.h}
+    viewBox={f.viewBox}
+    class={[cls, version === 'auto' && `logo-${f.v}`]}
+    style={style}
+    label={label}
+  >
+    <path fill={f.iconFill} fill-rule="evenodd" transform={`translate(${f.iconX} ${ICON_TOP}) scale(${ICON_SCALE})`} d={ICON_PATH} />
+    {f.word && <path fill={f.wordFill} transform={`translate(${f.wordX} 0)`} d={f.word.d} />}
+  </Fig>
+))}

package/dist/docs/src/content/components/button/accessibility.mdx

@@ -0,0 +1,18 @@
+---
+---
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| <kbd>Tab</kbd> | Moves focus to the button. |
+| <kbd>Enter</kbd> or <kbd>Space</kbd> | Activates the button. |
+
+## Requirements
+
+- Use a native `<button>` element. Ant Design Vue renders one.
+- Icon-only buttons need an `aria-label`.
+- Focus is shown with a 2 px ring in `color.border.focus`, 2 px away from the button (`border.width.focused`, `state.focus.offset`).
+- The target is at least 24 × 24px (WCAG 2.5.8).
+- Text and background meet 4.5:1 contrast in every state except disabled.
+- When `loading` is set, announce the result of the action when it finishes.

package/dist/docs/src/content/components/button/changelog.mdx

@@ -0,0 +1,6 @@
+---
+---
+
+## 0.1.0 – October 20, 2026
+
+- First documentation of Button. Early Access.

package/dist/docs/src/content/components/button/code.mdx

@@ -0,0 +1,27 @@
+---
+description: Use the Ant Design Vue button with the Beehexa theme.
+---
+import CodeExample from '../../../components/CodeExample.astro';
+
+## Installation
+
+Buttons come from Ant Design Vue. Apply the [Beehexa theme](/tools/ant-design-vue-theme/) once at the root of the app.
+
+## Usage
+
+<CodeExample lang="vue" code={`<template>
+  <a-space>
+    <a-button>Cancel</a-button>
+    <a-button type="primary" :loading="saving" @click="save">Save changes</a-button>
+    <a-button danger>Delete integration</a-button>
+  </a-space>
+</template>`} />
+
+## Props
+
+| Prop | Values | Notes |
+| --- | --- | --- |
+| `type` | `default`, `primary`, `link`, `text` | Use `primary` once per screen. |
+| `danger` | `boolean` | For destructive actions. |
+| `loading` | `boolean` | Shows a spinner and blocks repeat clicks. |
+| `disabled` | `boolean` | Prefer explaining why an action is unavailable. |

package/dist/docs/src/content/components/button/examples.mdx

@@ -0,0 +1,21 @@
+---
+---
+import CodeExample from '../../../components/CodeExample.astro';
+
+## Default
+
+<CodeExample code={`<button class="bh-button" type="button">Cancel</button>`} />
+
+## Primary
+
+Use one primary button for the main action on a screen.
+
+<CodeExample code={`<button class="bh-button bh-button-primary" type="button">Save changes</button>`} />
+
+## Danger
+
+<CodeExample code={`<button class="bh-button bh-button-danger" type="button">Delete integration</button>`} />
+
+## Disabled
+
+<CodeExample code={`<button class="bh-button bh-button-primary" type="button" disabled>Save changes</button>`} />

package/dist/docs/src/content/components/button/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Button",
+  "description": "A button triggers an action or event, such as submitting a form or opening a dialog.",
+  "group": "Actions"
+}

package/dist/docs/src/content/components/button/usage.mdx

@@ -0,0 +1,18 @@
+---
+---
+
+## When to use
+
+- To trigger an action: save, submit, sync, delete.
+- To open a dialog or start a flow.
+
+## When not to use
+
+- To go to another page. Use a link.
+- For many actions in a row. Use a dropdown menu for the less common ones.
+
+## Best practices
+
+- Start the label with a verb and keep it short: "Sync orders".
+- Put the primary button last in a group, on the right.
+- Ask for confirmation before destructive actions.

package/dist/docs/src/content/foundations/guidelines/accessibility.mdx

@@ -0,0 +1,19 @@
+---
+title: Accessibility
+description: Beehexa products meet WCAG 2.2 level AA.
+order: 1
+---
+
+## Our commitment
+
+Every Beehexa product meets [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA. Every component page has an Accessibility tab that says how the component meets it and what product teams still need to do.
+
+## Checklist
+
+- **Contrast**: text has at least 4.5:1 contrast with its background, large text and UI parts at least 3:1.
+- **Keyboard**: everything that works with a mouse works with a keyboard, in a logical order.
+- **Focus**: keyboard focus is always visible. Use a 2 px ring in `color.border.focus`, 2 px away from the element (`border.width.focused`, `state.focus.offset`).
+- **Target size**: pointer targets are at least 24 × 24 CSS pixels.
+- **Labels**: every control has a visible label or an accessible name.
+- **Motion**: respect `prefers-reduced-motion`.
+- **Errors**: say what went wrong in text, not only with color.

package/dist/docs/src/content/foundations/guidelines/content.mdx

@@ -0,0 +1,25 @@
+---
+title: Content
+description: How to write clear, concise and consistent product copy.
+order: 2
+---
+
+## Voice
+
+Clear, direct and helpful. Write for busy people who manage data across many systems.
+
+## Rules
+
+- Use sentence case for labels, headings and buttons.
+- Start buttons with a verb: "Save", "Sync orders", "Delete integration".
+- Keep one name for one thing across the product.
+- Use numerals for numbers: "3 orders failed".
+- Avoid jargon unless your readers use it.
+
+## Messages
+
+| Type | Write |
+| --- | --- |
+| Error | What happened, why, and how to fix it. |
+| Empty state | What will appear here and how to add the first item. |
+| Confirmation | The action and its consequence: "Delete 3 orders? This can't be undone." |

package/dist/docs/src/content/foundations/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Foundations
+description: Foundations create consistent user experiences. They include our design tokens, guidelines and visual styles.
+order: 0
+---
+
+Foundations are the decisions every Beehexa interface shares. They are grouped as design tokens, guidelines and styles.
+
+> Token values are provisional. They were taken from the current landing page while the team decides which system to base the values on.

package/dist/docs/src/content/foundations/styles/border.mdx

@@ -0,0 +1,89 @@
+---
+title: Border
+description: Four border widths, the colour each one goes with, and how the focus ring is drawn.
+order: 7
+---
+import ShapeDemo from '../../../components/ShapeDemo.astro';
+import TokenTable from '../../../components/TokenTable.astro';
+
+**Most borders are 1 px. Thicker lines mean something: selected, focused, or a status to notice.**
+
+Border colours are colour tokens: `color.border` for dividers and cards, `color.border.bold` for the edges of inputs, checkboxes and selects. See [Tokens](/foundations/styles/color/tokens/#borders).
+
+## The widths
+
+<ShapeDemo kind="border-scale" />
+
+## Examples
+
+### `border.width.default` · 1 px
+
+Inputs, secondary buttons, cards, tables and dividers.
+
+<ShapeDemo kind="border-use" item="default" />
+
+### `border.width.selected` · 2 px
+
+The bar under a selected tab, the bar beside a selected side navigation item, and the edge of a selected card. Always with `color.border.selected`.
+
+<ShapeDemo kind="border-use" item="selected" />
+
+### `border.width.focused` · 2 px
+
+The focus ring, in `color.border.focus`, drawn 2 px outside the element (`state.focus.offset`). Draw it inside, at −2 px, when a box around the element would cut it off: menu items, table cells and tabs in a scroll area.
+
+<ShapeDemo kind="border-use" item="focused" />
+
+### `border.width.accent` · 4 px
+
+A status or emphasis bar on one edge: alerts and banners, a table row with an error, callouts and quotes. The box keeps its radius on all four corners and the bar follows the curve.
+
+<ShapeDemo kind="border-use" item="accent" />
+
+## Width and colour go together
+
+| Width | Colour | For |
+|---|---|---|
+| `border.width.default` | `color.border` or `color.border.bold` | Edges and dividers |
+| `border.width.selected` | `color.border.selected` | Selected tab, side navigation item or card |
+| `border.width.focused` | `color.border.focus` | Keyboard focus |
+| `border.width.accent` | `color.border.danger`, `.warning`, `.success`, `.info` or `.brand` | Status and emphasis bars |
+
+Don't show a state with colour alone. Selected and focused also change the width.
+
+## Do and don’t
+
+<ShapeDemo kind="dodont" item="selected" />
+<ShapeDemo kind="dodont" item="accent" />
+<ShapeDemo kind="dodont" item="cards" />
+
+## Code
+
+```css
+.alert {
+  position: relative;
+  overflow: hidden;
+  border: var(--bh-border-width-default) solid var(--bh-color-border);
+  border-radius: var(--bh-radius-100);
+}
+.alert::before {
+  content: "";
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: var(--bh-border-width-accent);
+  background: var(--bh-color-border-danger);
+}
+:focus-visible {
+  outline: var(--bh-border-width-focused) solid var(--bh-color-border-focus);
+  outline-offset: var(--bh-state-focus-offset);
+}
+```
+
+## Tokens
+
+<TokenTable prefix="border" />
+
+## Related
+
+- [Radius](/foundations/styles/radius/): corner radius steps and the nesting rule.
+- [Interaction states](/foundations/styles/interaction-states/): hover, pressed, selected and disabled.

package/dist/docs/src/content/foundations/styles/color/accessibility.mdx

@@ -0,0 +1,32 @@
+---
+title: Accessibility
+description: The contrast every colour pair meets, which text may sit on which background, and how it is checked.
+order: 6
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Every text and icon token passes WCAG 2.2 AA on every background it is paired with, in light and in dark: all 386 pairs.**
+
+## Contrast
+
+| What | Minimum | WCAG 2.2 |
+|---|---|---|
+| Text | 4.5:1 | 1.4.3 |
+| Icons, control edges, focus ring | 3:1 | 1.4.11 |
+| Disabled controls, the yellow indicator bar, the logo | No minimum | 1.4.3 exception |
+
+<ColorDemo kind="contrast" />
+
+Colour is never the only signal (WCAG 1.4.1): statuses are written in words, selected items have a second cue.
+
+## Pairing
+
+**Text, icons and borders only go on the backgrounds listed with them.** Every pair here passes contrast in light and dark, and is checked on every build.
+
+<ColorDemo kind="pairing" />
+
+<ColorDemo kind="dodont" item="pairing" />
+
+## Checked automatically
+
+Every pair in [Pairing](#pairing) is checked automatically, in light and in dark. A text, icon or border token that falls below its minimum on any of its backgrounds is not released.

package/dist/docs/src/content/foundations/styles/color/dark-mode.mdx

@@ -0,0 +1,22 @@
+---
+title: Dark mode
+description: How the dark theme works, what changes and what you never do in dark.
+order: 5
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Write each token once; the theme changes the value.**
+
+<ColorDemo kind="themes" />
+
+## How it works
+
+Every colour token has a light and a dark value under the same name. The theme picks the value; your code and designs name the token once. The dark values of every palette step are on [Palette](/foundations/styles/color/palette/), and every role token's are on [Tokens](/foundations/styles/color/tokens/).
+
+## Designing for dark
+
+- Never write a dark colour of your own or pick colours by theme in code.
+- Surfaces get lighter as they rise: page darkest, cards one step lighter.
+- The primary button turns light, and the solid status fills get brighter with dark text on them.
+- Check every screen in both themes before release.
+- Logos use their dark-background versions (see [Logos](/foundations/styles/logos/)).

package/dist/docs/src/content/foundations/styles/color/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Color
+description: Three brand colours and a set of colour tokens with one job each, for text, icons, surfaces, backgrounds, borders and status, in light and dark.
+order: 1
+sidebarLabel: Overview
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+Colour in Beehexa products is mostly graphite and white. Yellow marks the brand, and four functional colours mark status. You never pick a colour by its value: you pick a token by its job, such as `color.text` or `color.background.danger.bold`, and it is right in light and in dark.
+
+<ColorDemo kind="balance" />
+
+## Brand colours
+
+<ColorDemo kind="brand" />
+
+## Palette
+
+Six scales of twelve steps, in light and dark. The brand graphite is graphite 12 in light; the brand yellow is yellow 7 in light and yellow 11 in dark. See every value in [Palette](/foundations/styles/color/palette/).
+
+<ColorDemo kind="ramps" />
+
+## How colour works
+
+Colour comes in three tiers. You only ever use the middle one.
+
+| Tier | Example | Who uses it |
+|---|---|---|
+| Palette | `color.graphite.11` | Nobody directly. It feeds the role tokens. |
+| Role tokens | `color.text.subtle` | Every product and component. |
+| Component tokens | `color.code.background` | Only where no role fits. |
+
+Role tokens are listed in [Tokens](/foundations/styles/color/tokens/); how to pick one is in [Usage](/foundations/styles/color/usage/).
+
+## Principles
+
+### Graphite does the work, yellow is the accent
+
+Text, icons, lines and the primary button are graphite. Yellow is only the logo, the current-page indicator, highlights and brand notes. It is never text and never a button: it is 1.85:1 on white.
+
+<ColorDemo kind="dodont" item="yellow" />
+
+### Colour means something
+
+Red, orange, green and blue mean danger, warning, success and info. Don't use them to decorate or to draw attention.
+
+<ColorDemo kind="dodont" item="meaning" />
+
+### Never colour alone
+
+Write the status in words and add an icon. Mark a selected item with a second cue besides colour. Colour blind people and screen reader users don't get the colour.
+
+<ColorDemo kind="dodont" item="alone" />
+
+### Use the token for the job
+
+Use role tokens only. Never a hex value, and never a step of a scale such as `color.graphite.11`. If no token fits, ask for one.
+
+<ColorDemo kind="dodont" item="tokens" />
+
+### One primary button per view
+
+The primary button is graphite. Every other button is a default button. There is no yellow button.
+
+<ColorDemo kind="dodont" item="primary" />

package/dist/docs/src/content/foundations/styles/color/palette.mdx

@@ -0,0 +1,57 @@
+---
+title: Palette
+description: Every colour in the system, as six scales of twelve steps in light and dark, what each scale and each step is for, and the contrast each step guarantees.
+order: 3
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**The palette feeds the role tokens. Products use the role tokens, never a palette step directly.**
+
+Six scales of twelve steps. Hover a swatch to see its token name.
+
+<ColorDemo kind="palette" />
+
+## What each scale is for
+
+| Scale | For | Never for |
+|---|---|---|
+| Graphite | Everything without a meaning: text, icons, lines, surfaces, the primary button | — |
+| Yellow | The brand: logo, current-page indicator, highlights, brand notes | Text, buttons, warnings |
+| Blue | Info, links, the focus ring | Decoration |
+| Green | Success | Anything else |
+| Orange | Warning | Anything else |
+| Red | Danger | Anything else |
+
+There is no purple, pink or teal. Charts have no palette yet: ask before colouring a chart.
+
+## What each step is for
+
+**Every step has one job, the same in every scale.**
+
+<ColorDemo kind="steps" />
+
+- **Steps 1–2:** page and surface backgrounds.
+- **Steps 3–5:** component backgrounds at rest, on hover and when pressed or selected.
+- **Steps 6–8:** borders and dividers, from subtle to strong.
+- **Steps 9–10:** solid fills, such as a button, and their hover.
+- **Steps 11–12:** text and icons. 11 is secondary, 12 is the default.
+
+Graphite carries the neutral text, so its dark end has three text levels instead of two: 12 default, 11 secondary, 10 tertiary. Step 9 is the edge of a control and step 8 is disabled text.
+
+Yellow is the one exception: its brand fill is step 7, the brand yellow, with graphite text on top. Products don't use yellow for other fills or for text.
+
+## Light and dark
+
+**Every step has a light and a dark value under the same name.**
+
+`color.graphite.12` is the text colour in both themes. The role tokens switch on their own, so a screen never picks a dark colour by hand. In dark, the solid fills (steps 9 and 10) are lighter than in light, so the text on them is dark: use `text.on-bold`.
+
+## Contrast you can count on
+
+In both themes:
+
+- In blue, green, orange and red, text on a solid fill (steps 9 and 10) reaches 4.5:1 with `text.on-bold`: white in light, dark in dark.
+- Step 11 text reaches 4.5:1 on every background it is paired with.
+- In graphite, steps 10, 11 and 12 all reach 4.5:1 as text; step 9 reaches 3:1 as the edge of a control.
+
+See [Accessibility](/foundations/styles/color/accessibility/) for the pairs.