# Wisesight Design System

Orientation and rationale for the Wisesight brand — the *why* behind the rules
and *how to build* with them. For the strict, auditable rule list use
[`llms.txt`](llms.txt); for importable values use
[`tokens.json`](tokens.json) / [`tokens.css`](tokens.css).

## The files (and when to use each)

| File | Audience | Use it to |
|------|----------|-----------|
| `index.html` | humans | Browse the interactive brandbook. **Source of truth.** |
| `llms.txt` | AI / reviewers | **Audit** a design — rules with IDs (`COLOR-03`) and MUST/SHOULD levels. |
| `tokens.json` | tools / devs | **Build** — exact values as data (colors, radius, shadows, spacing, type). |
| `tokens.css` | web devs | **Build** — drop-in `var(--ws-*)` custom properties. |
| `design.md` | humans | Understand the system and its rationale (this file). |

> Keep them in sync: `index.html` is canonical. When a rule changes there,
> update `llms.txt` and the token files in the same commit.

## The core idea: "One Voice"

Wisesight is evidence-first — we let the data lead. The visual system encodes
that personality: **mostly neutral, with a single deliberate point of focus.**
Neutrals (black, gray, white, real imagery) carry the content; one small red
accent directs the eye to the thing that matters. That restraint *is* the brand.

## The five decisions that define a Wisesight design

### 1. Small Red (the 10% rule)
Wisesight Red `#850219` appears in **every** layout, but only as ~10% or less —
a button, a key figure, a tag, an underline, one icon. Never a background, never
body text. **Why:** if everything is red, nothing is. Red is a spotlight, not
the stage. Test: remove the red — if the layout lost its focal point, it was
used right.

### 2. Neutral-first surfaces
Backgrounds are White, Gray-100 `#F2F3F6`, or Wisesight Black — or a Secondary
color when a context needs it. Additional (high-chroma) colors are **accents
only**, never backgrounds, capped at 20%. **Why:** a calm neutral field makes
the data and the red accent legible.

### 3. Flat by default, four gradients at most
Default to solid fills. The only gradients allowed are Red→Black and White→Gray,
each at 90° or 180°. On photos, use a **solid** dark overlay, not a gradient
scrim. **Why:** flat reads as confident and evidence-driven; ad-hoc gradients
read as decorative noise and fragment the brand.

### 4. Quiet, consistent geometry
Corner radius is only `0 / 5 / 10px` (or a full pill). There is exactly one
approved shadow (or none). Shapes come from an approved set. **Why:** a small,
fixed vocabulary makes everything feel like one product instead of many.

### 5. An 8px system
Build on a 12-column grid; size every margin, gap, and padding from an 8px base
(8 / 16 / 24 / 32 / 48 / 64). Keep desktop margins ≥ 48px. **Why:** rhythm and
breathing room are part of the brand; generous neutral space is intentional.

## Building with the tokens

Web (CSS):

```html
<link rel="stylesheet" href="tokens.css">
```
```css
.cta {
  background: var(--ws-red);
  color: var(--ws-text-on-red);
  border-radius: var(--ws-radius-md);   /* 10px */
  padding: var(--ws-space-2) var(--ws-space-3);
  box-shadow: var(--ws-shadow);
}
.card {
  background: var(--ws-surface-gray);
  border-radius: var(--ws-radius-md);
}
```

Any other tooling: read `tokens.json` (W3C design-tokens format) and map
`color.*`, `radius.*`, `shadow.*`, `spacing.*`, `typography.*` into your
platform.

## Typography

`Roboto` is the UI/system font. For slides, reports, and branded content use the
approved additional fonts: **Sarabun** (formal, Thai+Latin), **Prompt**,
**Kanit**, **Poppins**, **IBM Plex Sans**. One family per document; no other
typefaces.

## Logo (the short version)

Primary (dark) logo on light backgrounds; inverted on dark. The logo may sit
directly only on White, Gray-100, Black, or Red — on any other color, put the
primary logo in a white box. Keep clear space of one symbol-height on all sides.
Never stretch, rotate, recolor, or add effects. Full rules: `LOGO-*` in
`llms.txt`.

## Auditing a design with AI

1. Host this folder and copy the `llms.txt` URL (or click **Copy audit prompt**
   in the brandbook header).
2. Paste it into an AI with your design and ask for a per-rule audit.
3. The AI returns a `Rule ID | Level | Verdict | Evidence | Fix` table and an
   **ON-BRAND / OFF-BRAND** verdict.