Reconcile docs/design_guide.md with the code and the language policy #8

New issue

Open

opened 2026-09-19 17:50:10 +00:00 by gabogg · 0 comments

gabogg commented

2026-09-19 17:50:10 +00:00

Owner

Two tensions around docs/design_guide.md, surfaced by the PR #6 review, left unresolved on purpose:

Design-guide vs style variants. design_guide.md §8 says to vary "únicamente superficies de lectura … sin cambiar paleta ni geometría", but CONTEXT.md / docs/routes.md formalize rounded-glass and timeline-step as style variants that change geometry, and CLAUDE.md rule 2 endorses all three. The repo overrides the guide; §8 should be updated to reflect that the geometry-changing variants are sanctioned.
Language policy vs agent-directed sections. CLAUDE.md rule 4 keeps design_guide.md in Spanish as a product/visual reference, but its §7 ("INSTRUCCIÓN DIRECTA PARA EL AGENTE") and §9 (an agent checklist) address the agent directly. Decide: either move those agent-directed sections into the English agent docs, or restructure the guide so it is purely a product/visual reference.

Acceptance: §8 reconciled with the sanctioned variants, and the agent-directed sections either relocated to English agent docs or explicitly reframed as team-facing design intent.

Two tensions around `docs/design_guide.md`, surfaced by the PR #6 review, left unresolved on purpose: 1. **Design-guide vs style variants.** `design_guide.md` §8 says to vary *"únicamente superficies de lectura … sin cambiar paleta ni geometría"*, but `CONTEXT.md` / `docs/routes.md` formalize `rounded-glass` and `timeline-step` as style variants that change geometry, and `CLAUDE.md` rule 2 endorses all three. The repo overrides the guide; §8 should be updated to reflect that the geometry-changing variants are sanctioned. 2. **Language policy vs agent-directed sections.** `CLAUDE.md` rule 4 keeps `design_guide.md` in Spanish as a product/visual reference, but its §7 ("INSTRUCCIÓN DIRECTA PARA EL AGENTE") and §9 (an agent checklist) address the agent directly. Decide: either move those agent-directed sections into the English agent docs, or restructure the guide so it is purely a product/visual reference. **Acceptance:** §8 reconciled with the sanctioned variants, and the agent-directed sections either relocated to English agent docs or explicitly reframed as team-facing design intent.

gabogg added the

needs-triage

label

2026-09-19 17:50:10 +00:00

gabogg referenced this issue

2026-09-19 18:11:01 +00:00

docs: standardize repo docs and scaffold agentic-coding config #6

gabogg referenced this issue

2026-09-19 19:46:52 +00:00

docs: standardize repo docs and scaffold agentic-coding config #6

gabogg referenced this issue from a commit

2026-09-19 20:11:36 +00:00