# Design system (DS-1): the KimaAI brand in the plugin

Status: **design approved 2026-11-13** by the owner, with the proposal for every question below; built in DS-2 to DS-7. Storybook: "Design system/Foundations" and "Admin/Primitives".

## One brand for kimaai.com and the plugin

The website's design system (repository `../kimaai`, track DS, `docs/research/design-system.md`) was approved on 2026-11-13. The owner decided on 2026-11-13 that the website and the plugin share one brand system. The plugin therefore takes the website's tokens instead of a palette of its own:

- **Colours, radius, shadows, motion, focus ring and icon rules:** the website's values.
- **Names:** the plugin's own (`--kimaai-color-action` is the website's `--wp--preset--color--action`). On a customer's site, `--wp--preset--*` belongs to that site's theme.
- **Drift:** primitive suffixes match the website's, so DS-2 adds a check that the values stay equal (owner, 2026-11-13).

Already decided for the website and taken over as they are:

- Brand `#6767FD` is fixed. Buttons and links use action `#5250E6` (white on it: 5.76:1).
- Neutrals:

    | Role | Value |
    | ---- | ----- |
    | Headings (contrast) | `#010136` |
    | Text | `#23234A` |
    | Muted | `#545473` |
    | Tint | `#F5F7FF` |
    | Subtle | `#ECEEF8` |
    | Borders | `#E3E3F0`, `#CBCBE0` |

- **Night** for dark surfaces:

    | Role | Value |
    | ---- | ----- |
    | Night | `#0A0A24` |
    | Raised | `#15153A` |
    | Border | `#2A2A52` |
    | Text | `#F5F7FF` |
    | Muted | `#A9A9C8` |

- **Accents** sky, sun and coral are for decoration only. Status success, warning and danger each have a soft surface.
- **Radius:** 4 to 28 px (buttons 10 px, cards 20 px). Shadows are tinted towards the brand. Motion is 120, 200 and 360 ms, and reduced motion is respected. The focus ring is 2 px of surface, then 2 px of brand.
- **Icons:** Lucide at 1.75 stroke, 16, 20 and 24 px.
- **Logo:** the usage rules as approved for the website.

## What only the plugin needs (for approval)

Decided with the owner on 2026-11-13, shown in Storybook:

- **Fonts.** The website reads in Satoshi, but Satoshi's licence (Fontshare / Indian Type Foundry free font EULA) forbids redistributing the files (confirmed by the owner, 2026-11-13), so the plugin cannot bundle it.
    - The admin uses the WordPress admin's own font.
    - The chatbot inherits each site's font.
    - Geist Mono, the website's monospace (SIL OFL 1.1), is bundled in `assets/fonts/geist-mono/` for code and versions.
    - Yekan only for Persian (Farsi), keyed on the language (`:lang(fa)`), not on RTL: Arabic, Hebrew and other RTL languages keep their normal font (owner, 2026-11-13).
- **Dark mode** for the admin and the chatbot, built from the website's night palette.
- **Plugin-only tokens.** These are the colours the website does not define, all checked for contrast:

    | Token | Value | Why |
    | ----- | ----- | --- |
    | Input border, light | `#8888A6` | 3.43:1 on white; the website's `#CBCBE0` is 1.6:1, below WCAG 1.4.11's 3:1 for form controls |
    | Input border, dark | `#6E6EA3` | 3.68:1 on raised night |
    | Second dark surface | `#1E1E4A` | Text 14.65:1, muted 6.86:1 on it |
    | Dark status: success | `#4FD1A1` | 7.7:1 or more on night surfaces |
    | Dark status: warning | `#F2C94C` | 7.7:1 or more on night surfaces |
    | Dark status: danger | `#FF8A80` | 7.7:1 or more on night surfaces |

- **The chatbot's defaults.**
    - Light: header and user messages in action, bot messages on brand-faint, and borders, shadows and the 10 and 20 px radius from the website.
    - Dark: night-raised body, night header and footer, bot messages on `#1E1E4A`.
    - The four styles (classic, minimalist, glossy, neon) and the admin's colour presets and per-element overrides stay.
- **Outline buttons and links in dark mode** use brand-light `#B3B0FE` (8.8:1). As text on night, action is too dark.

## What the audit found (2026-11-13)

| Finding | Today | Effect |
| ------- | ----- | ------ |
| Two different purples | Admin `#6767fd`, chatbot `#4545f9` | The chatbot is off-brand |
| Buttons on `#6767fd` | White on it: 4.26:1 | Fails AA (the website found the same and moved buttons to action) |
| Admin dark text | Text `#d8d8d8` 11.43:1, muted `#cbd5e1` 10.98:1 | No hierarchy |
| Admin dark borders | `#334155` on `#162033`: 1.57:1 | Inputs and cards barely visible |
| Chatbot dark primary | `#4545f9` on `#0f172a`: 2.95:1 | Primary elements disappear |
| Neutrals | Tailwind slate, about 300 raw `slate-*`/`gray-*` and 327 `dark:` classes | Generic look; DS-3 moves them to role tokens |
| Persian font | Yekan, admin only, forced with `!important` | The chatbot shows Persian in the site's font |
| RTL stylesheets | Built, never enqueued | RTL relies on a few manual rules |

## What changes where (DS-2 to DS-7)

| Item | Change |
| ---- | ------ |
| DS-2 | `tokens.css` loaded by the admin (Tailwind 4 `@theme`) and the chatbot; the drift check against the website's tokens |
| DS-3 | Raw `slate-*`/`gray-*` and `dark:` classes replaced with role tokens; admin dark mode on `[data-kimaai-theme]` |
| DS-4 | Chatbot defaults and dark mode on the tokens; the four styles checked |
| DS-5 | Fonts: Geist Mono for code and versions, Yekan for Persian text only (`:lang(fa)`) in the admin and the chatbot without `!important`. The generated `*-rtl.css` stays unused: the chatbot's `.rtl` rules assume the LTR stylesheet, so swapping in the flipped one would mirror positions twice and override the owner's left/right choice |
| DS-6 | Kima primitives (button, modal, card, field, badge, notice, tabs, empty state) on the website's shapes; Lucide icons |
| DS-7 | AI disclosure notice in the widget (EU AI Act Art. 50); WCAG 2.2 AA checks in Storybook |

## Decisions (owner, 2026-11-13)

Approved as proposed:

1. **Dark mode from the night palette,** including the plugin-only tokens above. Approved.
2. **The chatbot's new defaults** (action header and user messages, brand-faint bot messages, website radius and shadows). Approved.
3. **Yekan in the chatbot** on Persian sites. Approved; Yekan only for Persian text, not for other RTL languages (owner, 2026-11-13).
4. **Digits in Yekan.** Yekan draws Latin digits as Persian digits ("300" shows as "۳۰۰"). Today the admin forces Yekan on every element on RTL sites, so versions, prices and counts show Persian digits too. Approved: Yekan for text, Geist Mono for numbers in code and versions.

## Sources

- Website design system: `../kimaai`, branch `track/ds-design-system`, `docs/research/design-system.md` and `storybook/styles/tokens.css` (approved 2026-11-13).
- Satoshi licence: [Adom font licensing notes](https://wiki.adom.inc/api/pages/adom/adom-theme/files/fonts/LICENSES.md), [Adom on Satoshi](https://wiki.adom.inc/api/pages/adom/adom-theme/files/fonts/satoshi/README.md), [Satoshi on fontalternatives.com](https://fontalternatives.com/fonts/satoshi/) (secondary sources; the owner confirmed the licence on 2026-11-13).
- Geist Mono: npm package `geist` 1.8.2, SIL OFL 1.1 (`assets/fonts/geist-mono/OFL.txt`).
- WCAG 2.2: [1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum), [1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast), [2.5.8 Target Size (Minimum)](https://www.w3.org/TR/WCAG22/#target-size-minimum).
