# Design System - Pollinator Oasis (Crown Bees Pollination App)

> **Durable document** (designated Session 370, 2026-07-13). The **4th** of the four canonical
> project documents per the Hub methodology **[[10-Three-Document-Product-Canon]]** (`~/Documents/
> Claude/Vaults/The Hub/25 Methodology/10-Three-Document-Product-Canon.md`). This is the **Design
> System** - it answers **"what is the visual + interaction language the product is built in?"**
> and is the canonical entry point the other three documents point to for the skin.
>
> **Version: v1.0** (first authoring; documents the shipped skin reconciled against `packages/ui`
> and the `crown-bees-design` brand authority). **Current shipped-skin coordinates: btt-server v61,
> client EAS build 24, product `main` `69ed4b5`.** Living copy: this file. Dated, version-stamped
> snapshots under `documents/snapshots/`. Companions: **As-Built** (`as-built-spec.md` - what is
> live), **UX Flow Atlas** (`ux-flow-atlas.md` - the desired experience per persona per flow), and
> **To Build** (`next-build-spec.md` - what we build next).
>
> **Shape: reference-hub, not a copy.** This document summarizes the design system faithfully and
> points to the authoritative sources (Section 8). It deliberately does NOT duplicate the token
> files or component source - those live once, in the skill and the code, and copying them here
> would create a drift surface. Reproduce from the authoritative sources named below; never
> re-draw from memory.

**IP notice.** The design system **is the Crown Bees brand** - the sole IP of **Dave Hunter /
Crown Bees, LLC**. The `crown-bees-design` skill's own notice governs: *"(c) 2026 Dave Hunter /
Crown Bees, LLC. All rights reserved. Confidential - not for distribution. Produced by Scott Sands
(advisor) and Claude under Scott's direction, on behalf of Dave Hunter / Crown Bees, LLC. No IP
claim by Scott Sands or Claude."* The Bee Team's combined IP is the **app** that implements this
brand, per `IP-NOTICE.md` - not the brand itself. When BT extends the DS with app-specific
components (the `@btt/ui` net-adds), those components are combined BT work product built in the
Crown Bees brand.

---

## Section 1 - The source-of-truth hierarchy

The design system exists authoritatively in **two layers**, and they can drift. This document's
first job is to name them and the rule between them.

| Layer | Where | Authority for |
|---|---|---|
| **Brand design authority** | `~/.claude/skills/crown-bees-design/` - `colors_and_type.css` (tokens as CSS custom properties), `README.md` (brand context, voice, visual foundations, iconography), `LOGO.md` (logo usage), `preview/` (token + component specimens), `ui_kits/marketing-site/` (faithful UI recreation), `assets/logos/` (official logo artwork) | The **design intent** - what the brand is. Extracted verbatim from the Crown Bees Pollination Success App v0.1 prototype; the prototype is the ultimate source, and where the skill and the prototype disagree, the prototype wins. |
| **Implemented** | product repo `packages/ui/src/tokens/*.ts` (the shipped tokens) + `packages/ui/src/components/*.tsx` + `charts/*.tsx` (the `@btt/ui` component library) | **What actually ships** - the As-Built reality. This is what renders in the app on iOS / Android. |

**The rule.** The brand design authority governs *intent*; `packages/ui` governs *what is live*.
Where a shipped value differs from the brand authority, that is a **drift to reconcile** - the
implemented value is what the user sees (and so what the As-Built records), while the brand
authority states what it should be. Known drift is listed in Section 8 so neither layer is read as
complete on its own. New work reproduces from **both**: the brand authority for the rules and
voice, `packages/ui` for the exact shipped tokens and component APIs.

Building a new screen is **compose-from-the-kit**, not a reskin: the live app skin already **is**
this design system.

---

## Section 2 - Color

**Two brand colors carry everything.** Green is frame / heading / structure; orange is the **only**
call-to-action color, used sparingly so it always reads as "do this."

| Role | Hex | CSS var (skill) | Code token (`packages/ui`) |
|---|---|---|---|
| **Brand green** (primary) | `#004322` | `--cb-green` | `colors.green` |
| Green dark (hover / pressed) | `#002e17` | `--cb-green-dark` | `colors.greenDark` |
| Green light (hero terminus) | `#1d6a44` | `--cb-green-light` | `colors.greenLight` |
| **Action orange** (only CTA) | `#e69100` | `--cb-orange` | `colors.orange` |
| Orange light (pale surface) | `#fff6e6` | `--cb-orange-light` | `colors.orangeLight` |
| Orange dark (hover / pressed) | `#b87100` | `--cb-orange-dark` | `colors.orangeDark` |

**Semantic status trio** (GO / WAIT / HOLD): success green `#28a745` (`--cb-success` / `colors.success`),
warning amber `#eb9247` (`--cb-warning` / `colors.warning`), alert red `#e95050` (`--cb-red` /
`colors.red`). Red also carries "sale."

**Warm neutrals** (never cold grey): text `#222222`, muted `#6b6760`, soft `#888888`, white surface
`#ffffff`, page field `#f8f8f8`, cream highlight `#fdf6e6`, hairline border `#e6e3dd`, faint divider
`#f0ede6`. (Code tokens: `colors.text` / `textMuted` / `textSoft` / `bg` / `bgSoft` / `bgCream` /
`border` / `borderSoft`.)

**IP / confidentiality band palette** (always-on notices): parchment `#fdf6e3` (`--ip-bg`), brown
text `#6b5a2c` (`--ip-text`), gold border `#ecd9a3` (`--ip-border`).

**Status-pill tints** (pale bg + saturated text), via `pillTints` in code:

| Tone | bg | fg |
|---|---|---|
| green | `#e6f5ec` | `#28a745` |
| orange | `#fff2e0` | `#b87100` |
| red | `#fce8e8` | `#e95050` |
| blue | `#e6f0f7` | `#2c5fa3` |
| grey | `#ececec` | `#6b6760` |

**Chart accent palette** (added S209 / S242; implemented in `colors.ts`, see Section 8 drift note):
clay `#bd6b43` (early-tier / harvest / temp) + claySoft `#f4e6dc`; sage `#74886b` (mid-tier /
Summer Leaf) + sageSoft `#eef2e9`; sky `#2c5fa3` (late-tier / threshold / GDD) + skySoft `#e6f0f7`
/ skyBorder `#cfe0ee`; plum `#7a5ea8` (Huckleberry).

---

## Section 3 - Typography

**A single family: Inter** (weights 400-800), loaded via `@expo-google-fonts/inter` in the app and
Google Fonts in the skill. System-mono fallback (`SF Mono, Menlo, Consolas`) for code / labels only.
No serif in the live app.

**Font-family tokens** (`fontFamily` in `typography.ts`): `Inter_400Regular`, `Inter_500Medium`,
`Inter_600SemiBold`, `Inter_700Bold`, `Inter_800ExtraBold`.

**Scale** (size / weight / tracking), from `fontSize` + `fontWeight` + `letterSpacing`:

| Role | Size | Weight | Tracking | Note |
|---|---|---|---|---|
| hero | 36 | 800 | - | welcome hero h1 |
| h1 | 30 | 800 | -0.3 | display, tight + heavy |
| h2 | 22 | 700 | -0.2 | |
| h3 | 16 | 700 | - | |
| lead | 17 | 400 | - | intro paragraph, muted |
| body | 15 | 400 | - | line-height 1.5 (= 22.5) |
| small | 13 | 400 | - | captions / muted |
| micro | 11.5 | 500 | - | IP band, eyebrow (uppercase, +0.3 tracking) |

Display is tight and heavy; body is comfortable at 15/1.5.

---

## Section 4 - Spacing, radii, elevation, layout, motion

- **Spacing** (4px base, sparse map - reproduce the exact keys), `spacing` token:
  `1:4 / 2:8 / 3:12 / 4:16 / 6:24 / 8:32 / 12:48`.
- **Radii**, `radii` token: default `10`, lg `14` (cards / heroes / banners), xl `20`, pill `999`.
- **Elevation:** exactly **one shadow** in the system - the sticky header
  `0 1px 4px rgba(0,0,0,0.08)` (`shadows.header`, platform-aware via `Platform.select`). **Cards
  carry NO shadow** - a 1px warm border + 14px radius does the separating.
- **Layout:** content capped at **980px** centered, 16px side gutters (`--max-width` / `--gutter`).
- **Motion** (minimal, quick): screen fade-in `0.18s ease` (opacity 0->1, translateY 4px->0);
  hover / press `0.12s ease`; progress-bar width `0.4s`. No bounces, loops, or parallax.
- **Signature gradients (the only two):** the welcome **hero** `linear-gradient(135deg, green ->
  green-light)` and the **GDD progress bar** `linear-gradient(90deg, green -> orange)`. Everything
  else is a flat fill - no photography, textures, or patterns.

---

## Section 5 - Component vocabulary (`@btt/ui`)

The implemented library lives at `packages/ui/src/`; import from `@btt/ui`. Each has a test in
`__tests__/`. Compose screens from these; a component not already here is a **net-add** (flag it).

**Primitives:**
- `Button` - variants primary / outline / outlineOnDark / secondary / ghost / green / heroLight;
  sizes sm / md / lg. Hover darkens to the `-dark` token; disabled = 0.5 opacity.
- `Pill` - 5 tones (Section 2 tints); `toPillLabel` Title-Cases + strips punctuation, all-caps
  tokens survive. GO / WAIT / HOLD is **`DecisionBanner`**, not a Pill.
- `Card` - white fill, 1px warm border, 14px radius, no shadow; padding default 24 / tight 16.
- `Typography` - the Section 3 variant scale.
- `DecisionBanner` - the large, full-color GO / WAIT / HOLD banner (the app's most saturated
  surface, reserved for the daily release call). Distinct from Pill.
- `TopProgressBar` - the top loading line = the header's idle orange underline.

**Content components:** `Hero`, `DetailHero`, `StepCard`, `KvList`, `GddBar`, `PlantCard`,
`AddPlantCard`, `AdviceItem`, `KnowledgeCard`, `BloomConfirmRow`, `AlertFeedRow`,
`SpeciesAccordion`, `ActionDetailSheet`, `WeeklyTipSheet`, `TodayWeatherCard`, `WeatherGrid`,
`HomeSummaryCards`.

**Charts** (`packages/ui/src/charts/`): `ChartFrame`, `GddYearChart`, `PollenGauge`,
`VarietyTimelineChart`, `TempActiveBeesChart`, `BlossomWindowsChart` (+ `gdd-geometry` / `scale`
helpers).

**Chrome** (app-level, in `apps/client`, built on the kit):
- **SiteHeader** - green `#004322` app bar on every signed-in screen: orange-bee CROWNBEES
  wordmark -> Home, notifications bell -> Advice (orange unread badge), avatar -> Profile, a 3px
  orange bottom line (`TopProgressBar`). Mobile below 980px; horizontal nav row at/above 980px.
- **BottomTabBar** - white, mobile-only, five slots: **Home / Weather / [center orange "Ask" FAB]
  / Yard / Advice**. The FAB (54x54, orange, floating) is the Rep-AI "Ask" entry point (BT-062).

---

## Section 6 - Voice + iconography

**Voice** (from the prototype's copy): warm, plain-spoken, confidence-building - an expert
gardener, never a marketer.

- **Second person, possessive:** "your garden", "your bees", **My** Plants, **your** Crown Bees
  cart. The app speaks as "we" (Crown Bees).
- **Sentence case** for body and most headings. The three decision verbs **GO / WAIT / HOLD** are
  the only shouted words (plus all-caps status pills like `BLOOM ACTIVE`). Nav labels are Title
  Case ("My Plants", "Weather & Bees").
- **Action-oriented:** every screen reduces to a clear next action. Domain terms (Growing Degree
  Days, cocoons, hatchery) always paired with a plain consequence.
- **Concrete numbers**, no vague intensifiers. Contractions used freely.

**Iconography = emoji, used functionally** (never decoratively). No SVG / icon-font / line-icon
set - introducing one (Lucide / Heroicons / etc.) breaks from the source; flag if a true icon is
unavoidable.

- **Plant glyphs:** apple, pear, cherry, blueberry, peach, strawberry / raspberry, almond / nut,
  garden flowers.
- **Status / weather:** check (pass / GO), cross (fail), hourglass (wait), shield (guard), sprout,
  bee, bird, and the sun / cloud / rain forecast set.
- Keep new emoji at the same functional scale (22-36px).

---

## Section 7 - Logo + IP band

**The mark:** an apple / berry (a fruit body with two leaves holding seven seeds, one a **bee**)
locked up with the **CROWNBEES** wordmark (CROWN green, BEES orange). Current selection is
**"Option 2"** - a solid orange-disc bee (full color) / negative-space ring (reversed). Official
artwork lives in `assets/logos/`; never recolor or rebuild it.

| File | Role | Use on |
|---|---|---|
| `crown-bees-horizontal.png` | Primary - horizontal, full color | light backgrounds |
| `crown-bees-vertical.png` | Primary - vertical, full color | square spaces, app icons, badges |
| `crown-bees-horizontal-ondark.png` | Reversed - horizontal | Crown Green / dark backgrounds |
| `crown-bees-vertical-ondark.png` | Reversed - vertical | Crown Green / dark backgrounds |

**Logo color note:** the logo's orange is the artwork's own gold-orange `#F0A010` - intentionally a
hair warmer than the UI action orange `#e69100`. **Keep the logo's built-in orange; do not recolor
it to the UI token.** Clear space = the height of the "C" in CROWNBEES on all sides. Minimum ~120px
wide (horizontal) / ~90px tall (vertical) on screen. For infinite-scale print, request the original
vector from Crown Bees. Full rules: `LOGO.md`.

**IP / confidentiality band** appears on every brand surface and MUST stay visible: *"(c) 2026 Dave
Hunter / Crown Bees, LLC. All rights reserved. Confidential - not for distribution."* Rendered in
the parchment / brown / gold IP palette (Section 2). Blocks in `assets/ip-notice.html`.

---

## Section 8 - The authoritative sources (the link hub) + known drift

**Point here for exhaustive detail; reproduce from these, never from memory:**

| Source | Path | Authority for |
|---|---|---|
| Brand tokens (CSS) | `~/.claude/skills/crown-bees-design/colors_and_type.css` | Color + type + spacing + radii + motion, as design intent |
| Brand context / voice | `~/.claude/skills/crown-bees-design/README.md` | Brand story, copy voice, visual foundations, iconography |
| Logo usage | `~/.claude/skills/crown-bees-design/LOGO.md` | Logo files, color, clear space, do / don't |
| Token + component specimens | `~/.claude/skills/crown-bees-design/preview/` | Rendered color / type / spacing / component cards |
| UI-kit recreation | `~/.claude/skills/crown-bees-design/ui_kits/marketing-site/` | A faithful HTML recreation of the app + storefront |
| Implemented tokens | `packages/ui/src/tokens/*.ts` (product repo) | The **shipped** color / type / spacing / radii / shadow values |
| Implemented components | `packages/ui/src/components/*.tsx` + `charts/*.tsx` | The `@btt/ui` component APIs actually shipped |
| Full skin reference (narrative) | `outputs/s305/THE-BUILD-SPEC.md` Appendix A | The reproduction-grade skin write-up that seeded this document |

**Known drift between the two layers** (the implemented layer leads the brand-authority layer;
reconcile when the DS is next revised):

1. **Radii xl:20.** `packages/ui` `radii` carries an `xl: 20` step the skill's `colors_and_type.css`
   does not list (skill has default 10 / lg 14 / pill 999). `xl:20` is shipped and canonical.
2. **Chart accent palette.** `colors.ts` carries the clay / sage / sky / plum chart accents (+ their
   soft tints, `skyBorder`) added S209 / S242; `colors_and_type.css` does not yet carry them. They
   are shipped, documented in THE-BUILD-SPEC Appendix A, and canonical - not yet back-ported to the
   skill CSS.

Neither drift is a defect in the app; both are the brand-authority CSS lagging shipped additions.
A future DS revision should back-port them into the skill so the two layers reconcile.

---

## Section 9 - Versioning and provenance

**This document carries its own version, decoupled from product semver.** The As-Built version
tracks production (it changes on every build); the design system changes far less often - only when
the DS itself changes (a new token, a new `@btt/ui` component, a palette or type shift). So the DS
version bumps on DS changes, and the shipped-skin coordinates (server release, client build,
commit) are pinned in the header for reference at authoring time.

**v1.0** - first authoring, Session 370 (2026-07-13). Reference-hub over the two authoritative
layers, reconciled against `packages/ui` at product `main` `69ed4b5` and the `crown-bees-design`
skill. Shipped-skin coordinates: btt-server v61, client EAS build 24.

**Provenance.** The design system was extracted from the Crown Bees Pollination Success App v0.1
prototype (`~/Documents/Claude/Vaults/Crown Bees/Crown-Bees-Pollination-App/prototype/index.html`)
into the `crown-bees-design` skill, then implemented in `packages/ui`. This document consolidates
the As-Built Section 4 skin summary and the THE-BUILD-SPEC Appendix A reference into the canonical
DS entry point, per Scott's Session 369 direction that the Design System become the 4th canon
document. It is a reference-hub (Option A), not a copy - the token files and component source
remain the single source of truth in the skill and the code.

---

*Design System v1.0 - The Bee Team. The 4th canonical product document per the Hub Three-Document
Product Canon methodology (expanded to four at Session 369-370). The design system is the Crown
Bees brand (Dave Hunter / Crown Bees, LLC sole IP); the app that implements it is combined BT IP.
Reference-hub over two authoritative layers - the `crown-bees-design` brand skill (intent) and
`packages/ui` (what ships). Change history lives in git + the LMA records + the dated snapshots,
never this footer.*