Update DESIGN.md

DESIGN.md

@@ -0,0 +1,60 @@
+# Design Guide
+
+<!-- Generated by CodePress style analysis. -->
+
+This repository is a Python/Django backend library (`deux`, a two-factor-auth package for Django REST Framework). It has no application frontend — no `package.json`, no JS/TS, no Tailwind, no React/Vue. The only styling surface in the repo is a hand-written Sphinx documentation theme (`docs/theme/deux/static/deux.css_t`, forked from Armin Ronacher's Celery theme). I'll ground every claim in that file and the package manifests.
+
+SECTION 1: Primary Styling System
+‣ Brand feel / mood: Classic open-source docs site with a clean white canvas, fixed-width centered layout, serif-flavored humanist body type, and a single fintech-green accent — restrained and developer-documentation-oriented, not a product UI.
+‣ One-word system: Sass — closest match is "Sass/Mixed", because the sole stylesheet is a hand-authored Sphinx CSS template (`deux.css_t`) using Jinja `{% set %}` variables for fonts/widths rather than any component framework; there is no Tailwind, CSS Modules, or CSS-in-JS anywhere in the repo.
+‣ Breakpoints found in the repo: None — the theme uses fixed pixel widths (`page_width = 940px`, `sidebar_width = 220px`) and contains zero `@media` queries, so the layout is non-responsive.
+
+SECTION 2: Other Styling Signals
+‣ Secondary styling systems present with rough % prevalence:
+- Hand-written CSS (Sphinx `.css_t` template): ~100% of all styling in the repo.
+- Tailwind / CSS-in-JS / CSS Modules / component libraries: 0% (none present).
+- Inline styles / app templates: 0% (no HTML templates or front-end app exist; this is a backend Python package).
+‣ Evidence snippets (≤120 chars each):
+- `a { color: #21CE99; text-decoration: underline; }  a:hover { color: #17AD7B; }`
+- `{% set body_font_stack = 'Optima, Segoe, "Segoe UI", Candara, Calibri, Arial, sans-serif' %}`
+- `div.document { width: 940px; margin: 0 auto; }`
+
+SECTION 3: Repo-Level UI Context
+‣ Framework: Unknown (no front-end framework; this is a Django REST Framework backend library — `djangorestframework`, `django-oauth-toolkit`, `django-otp` in requirements/default.txt).
+‣ Language split: Python (no TypeScript or JavaScript in the repo).
+‣ UI libraries: None — the docs build on Sphinx with a custom theme inheriting `basic` (`docs/theme/deux/theme.conf`); no shadcn/ui, Radix, MUI, or Bootstrap.
+‣ Pre-processors and CSS-in-JS: None — styling is a single plain-CSS Sphinx template (`deux.css_t`); no `.scss`/`.less`, no styled-components/emotion.
+‣ State libraries: Unknown / not applicable (no front-end app; backend uses Django models, services, and serializers).
+‣ Color palette:
+- Accent (brand link): `#21CE99` green, hover `#17AD7B` — defined on `a` / `a:hover` in `deux.css_t` (the brand's signature color).
+- Neutral text: body `#3E4349`, base text `#000`, muted footer/sidebar `#888` / `#555` / `#444`.
+- Surfaces / backgrounds: page `#ffffff`; tinted greens `#F2FCEE` (related bar), `#F0FFEB` (inline code), `#E8EBEF` (pre blocks), `#DCF0D5` / `#C7ECB8` (green borders).
+- Admonition states: note/topic `#eee`, seealso `#ffc` border `#ff6`, warning `#ffe4e4` border `#f66`, highlight `#FAF3E8`.
+- Where tokens live: literal hex values inline in `docs/theme/deux/static/deux.css_t`; fonts/widths are Jinja `{% set %}` variables at the top of that file. No design-token system.
+‣ Typography:
+- Body font: `Optima, Segoe, "Segoe UI", Candara, Calibri, Arial, sans-serif` at `font-size: 17px`.
+- Headline font: `Futura, "Trebuchet MS", Arial, sans-serif`, `font-weight: normal`.
+- Monospace: `'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace` at `0.9em`.
+- Scale: percentage-based headings — h1 200%, h2 180%, h3 150%, h4 130%, h5/h6 100%; body line-height ~1.4em.
+- Conventions: headings always `font-weight: normal` (never bold) in the headline font; links are underlined and use the green accent.
+‣ Spacing & layout:
+- Centered fixed-width column: `div.document { width: 940px; margin: 0 auto; }` with a `220px` left sidebar (`bodywrapper` margin-left 220px).
+- No spacing scale/token system; ad-hoc px/em margins (e.g. headings `margin: 30px 0 10px`, lists `margin: 10px 0 10px 30px`).
+- Layout primitive: float-based (`div.documentwrapper { float: left }`), not flex/grid.
+‣ Shape & elevation:
+- Corner radius: minimal — `border-radius: 2px` only on `pre` code blocks (with `-moz-`/`-webkit-` prefixes); everything else is square.
+- Depth: mostly flat with 1px solid borders (`#ccc`, `#888`, green `#C7ECB8`); subtle shadow `box-shadow: 2px 2px 4px #eee` on `img.screenshot` and `table.docutils`.
+‣ Component patterns:
+- Code block (`pre`): `background: #E8EBEF; padding: 7px 10px; margin: 15px 0; border: 1px solid #C7ECB8; border-radius: 2px;`
+- Inline code (`tt`): `background: #F0FFEB; color: #222;` in the monospace stack at `0.9em`.
+- Link (the brand element): `color: #21CE99; text-decoration: underline;` → hover `#17AD7B`; reference links use `border-bottom: 1px dashed #DCF0D5` → hover solid `#6D4100`.
+- Sidebar input: `border: 1px solid #ccc; font-family: <body stack>; font-size: 1em;`
+- Admonition/callout: `background: #fafafa;` with top/bottom `1px solid #ccc` borders, title in the headline font at `24px`, `font-weight: normal`.
+
+SECTION 4: Guidance for Downstream LLM
+‣ Do treat `#21CE99` (hover `#17AD7B`) as the single brand accent — use it for links and primary emphasis, and keep links underlined as the existing theme does.
+‣ Do keep the green-tinted neutral surfaces already in use (`#E8EBEF` for code blocks, `#F0FFEB` for inline code, `#F2FCEE` for bars) instead of introducing new background colors.
+‣ Do set headings in the Futura/Trebuchet headline stack with `font-weight: normal` and the percentage scale (200/180/150/130/100%); do not bold headings or add new font families beyond the three defined stacks.
+‣ Don't introduce Tailwind, CSS-in-JS, CSS Modules, or any component framework — all styling is hand-written CSS in `docs/theme/deux/static/deux.css_t`; edit that file directly.
+‣ Don't add new corner-radius values — the theme uses square edges with a single `2px` radius on code blocks; reuse `2px` or none.
+‣ Don't add new elevation styles — reuse the existing flat 1px borders and the lone `box-shadow: 2px 2px 4px #eee`; avoid new shadow levels, and don't add `@media`/responsive breakpoints since the layout is intentionally fixed-width.