---
id: glyco-design-system
title: Glyco Design System — AI-First Documentation
version: 1.0.0
date: 2026-06-09
audience: [ai-agents, engineers, designers]
language: en (product copy samples in pt-BR)
source-of-truth:
  tokens: src/app/globals.css
  primitives: src/components/ui/
  architecture: docs/ARCHITECTURE.md
status: living-document
---

# Glyco Design System

**Glyco** is a clinical platform (EHR + AI copilot) for Brazilian endocrinologists and
sports-medicine physicians. This design system documents everything an AI agent or human
needs to build, extend, or review Glyco surfaces: brand, voice, design tokens, components,
interaction patterns, and the technical architecture they live in.

> **If you are an AI agent: read this file first, then jump to the chapter you need.
> [06-ai-guidelines.md](06-ai-guidelines.md) contains the condensed decision rules —
> if you only read two files, read this one and that one.**

## Chapters

| # | File | Contents | Read when you need to… |
|---|------|----------|------------------------|
| 01 | [01-brand.md](01-brand.md) | Identity, logo assets, product naming, voice & tone, marketing messaging, compliance | Write copy, name a feature, use the logo, pitch the product |
| 02 | [02-foundations.md](02-foundations.md) | Color tokens (light/dark/high-contrast), typography, spacing, radii, elevation, motion, glass material, iconography | Style anything |
| 03 | [03-components.md](03-components.md) | UI primitives inventory, variants, forms, feedback, charts, component conventions | Build or modify a component |
| 04 | [04-patterns.md](04-patterns.md) | Dashboard shell, bento grid, composer/copilot surfaces, clinical data display, accessibility patterns | Compose a page or flow |
| 05 | [05-architecture.md](05-architecture.md) | Stack, routes, data layer (Supabase/RLS), AI/copilot runtime, security, testing, deploy | Touch anything server-side or structural |
| 06 | [06-ai-guidelines.md](06-ai-guidelines.md) | Condensed do/don't rules for AI agents generating code, UI, or copy in this repo | Always — before writing code |
| — | [tokens.json](tokens.json) | Machine-readable token export (colors, type, radii, elevation, motion) | Programmatic token access |

## The system in one paragraph

Glyco's visual language is **iOS 26 Liquid Glass adapted for web**: translucent layered
surfaces (`backdrop-filter` blur + saturation + specular highlight) over a near-neutral
canvas, an **iOS systemBlue primary** (`oklch(0.52 0.21 252)`), **SF Pro Display**
typography on the iOS Dynamic Type scale, **emerald/amber/red clinical semantics** that are
never the only signal channel, pill-shaped buttons with spring press feedback, and
dark-mode-first theming via a `.dark` class. All tokens are OKLCH CSS custom properties in
`src/app/globals.css`, exposed to Tailwind v4 through `@theme inline`. The product speaks
**Brazilian Portuguese** in a warm, direct, clinical voice ("você/seu", imperative CTAs,
CFM/SBEM terminology, almost no emoji). Everything ships WCAG 2.1 AA: visible focus rings,
`prefers-reduced-motion` and `prefers-reduced-transparency` fallbacks, 44px hit areas, and
color-plus-text semantics.

## Canonical sources (when docs and code disagree, code wins)

| Domain | Canonical source | Notes |
|--------|------------------|-------|
| Design tokens | `src/app/globals.css` | ~2,600 lines; OKLCH; `@theme inline` for Tailwind v4 |
| Legacy token layer | `src/design-system/tokens/colors.css` | Teal accent ramp; only consumed by `src/design-system/primitives/glass.module.css`. **Do not extend.** |
| UI primitives | `src/components/ui/` | @base-ui/react + CVA |
| Feature-sliced rules | `docs/ARCHITECTURE.md` + `.dependency-cruiser.cjs` | `app → features → design-system → lib` |
| Brand mark | `src/components/layout/glyco-icon.tsx`, `src/components/layout/logo.tsx`, `src/app/icon.svg` | Theme-aware via `var(--foreground)` |
| Copilot persona | `src/lib/ai/system-prompts.ts` | pt-BR clinical advisor; never diagnoses |
| Framework caveat | `AGENTS.md` (repo root) | Next.js 16 — read `node_modules/next/dist/docs/` before writing framework code |

## Versioning

This documentation is generated from the codebase at the commit it ships in. When you
change a token, component variant, or pattern, update the matching chapter in the same PR.
A chapter that contradicts the code is a bug — fix the chapter or the code.