docs(design): align token contract and skill

[jeanduplessis]

Summary

Align Kilo design documentation and agent guidance with design-token contract v0.2.0.

Why this change is needed

DESIGN.md and kilo-design guidance described older brand, surface, typography, radius, and status values. Agents could preserve stale implementation choices or introduce UI inconsistent with current token contract.

How this is addressed

• Replaces obsolete design definitions with exact v0.2.0 color, typography, radius, spacing, syntax, diff, and status-domain tokens.
• Makes root DESIGN.md canonical for token values and treats conflicting implementation as drift.
• Updates Kilo design references with compliant Tailwind utilities, surface roles, type utilities, touch sizing, and motion guidance.
• Adds maintenance guidance for keeping skill references aligned with design contract.

Human Verification

• Compared documented values and roles against supplied v0.2.0 token contract.
• Searched updated skill guidance for retired brand colors, stale calculated radii, resolved font warnings, and obsolete input styling.

Reviewer Notes

Human Reviewer Flags

• DESIGN.md becomes explicit source of truth over current CSS/component behavior when they differ.
• Token contract removes older display and heading roles in favor of fixed product roles.

Code Reviewer Agent

Code Reviewer Notes

• Existing frontend implementation drift is documented as drift rather than changed in this documentation-only PR.
• Unrelated local AGENTS.md change remains uncommitted and excluded.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.agents/skills/kilo-design/SKILL.md	17	Root DESIGN.md is still treated as the mandatory source for apps/mobile, even though mobile currently uses a separate token/font system.

Files Reviewed (10 files)

• .agents/skills/kilo-design/AGENTS.md - 0 issues
• .agents/skills/kilo-design/SKILL.md - 1 issue
• .agents/skills/kilo-design/reference/color-and-contrast.md - 0 issues
• .agents/skills/kilo-design/reference/kilo-brand.md - 0 issues
• .agents/skills/kilo-design/reference/motion-design.md - 0 issues
• .agents/skills/kilo-design/reference/spatial-design.md - 0 issues
• .agents/skills/kilo-design/reference/typography.md - 0 issues
• AGENTS.md - 0 issues
• DESIGN.md - 0 issues
• apps/web/src/app/globals.css - 0 issues

Fix these issues in Kilo Cloud

Previous Review Summary (commit 240df46)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 240df46)

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	3
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.agents/skills/kilo-design/SKILL.md	17	Web DESIGN.md is now treated as the mandatory source even for apps/mobile, which still uses a separate token/font system.
.agents/skills/kilo-design/reference/motion-design.md	23	Guidance forbids legacy yellow RGBA values while pointing to pulse-glow / animate-pulse-once, which still hardcode them.
.agents/skills/kilo-design/reference/typography.md	172	Guidance uses bodyLg, but the implemented utility class is type-body-lg.

Files Reviewed (8 files)

• .agents/skills/kilo-design/AGENTS.md - 0 issues
• .agents/skills/kilo-design/SKILL.md - 1 issue
• .agents/skills/kilo-design/reference/color-and-contrast.md - 0 issues
• .agents/skills/kilo-design/reference/kilo-brand.md - 0 issues
• .agents/skills/kilo-design/reference/motion-design.md - 1 issue
• .agents/skills/kilo-design/reference/spatial-design.md - 0 issues
• .agents/skills/kilo-design/reference/typography.md - 1 issue
• DESIGN.md - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by gpt-5.4-2026-03-05 · Input: 68.4K · Output: 8.2K · Cached: 240.1K}

_{Review guidance: REVIEW.md from base branch main}