|
|
|
|
|
---
|
|
|
|
|
|
title: Documentation Authoring Rules
|
|
|
|
|
|
type: guide
|
|
|
|
|
|
audience: human + agent
|
|
|
|
|
|
authority: canonical — how docs in this corpus are written and edited
|
|
|
|
|
|
status: current
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# Documentation Authoring Rules
|
|
|
|
|
|
|
|
|
|
|
|
How to create and edit documentation in this repo. These rules exist because the
|
|
|
|
|
|
corpus is meant to read as a coherent, drift-free reference (and a future book) —
|
|
|
|
|
|
not as an accreting pile of notes. Read [`docs/README.md`](./README.md) first for
|
|
|
|
|
|
the map; this file is the *how-to-write* layer.
|
|
|
|
|
|
|
|
|
|
|
|
The rules are not aesthetic. Each one fixes a failure that actually happened
|
|
|
|
|
|
during the corpus migration.
|
|
|
|
|
|
|
|
|
|
|
|
## 1. Link the canon — never copy it
|
|
|
|
|
|
|
|
|
|
|
|
**The one law.** If you need to state a family, an intent, a verb, a size, a
|
|
|
|
|
|
color role, or any other canonical value, **link the canon** — do not paste a
|
|
|
|
|
|
copy.
|
|
|
|
|
|
|
|
|
|
|
|
- Semantic vocabulary → link [`CANON.md`](./CANON.md).
|
|
|
|
|
|
- Token scope / color model → link [`canon/tsc.md`](./canon/tsc.md) and `THEMING.md §25`.
|
|
|
|
|
|
- A second copy is a future drift. This is literal: "7 families" survived in
|
|
|
|
|
|
three docs for weeks after the canon moved to 8, because each doc had
|
|
|
|
|
|
re-transcribed the list instead of linking it.
|
|
|
|
|
|
|
|
|
|
|
|
The doctrine fixes the *doctrine*; the code fixes the *numbers*. When a value
|
|
|
|
|
|
lives in code (per-family holds, channel signatures, full verb lists), **link
|
|
|
|
|
|
the `file:symbol`**, don't snapshot it into prose.
|
|
|
|
|
|
|
|
|
|
|
|
## 2. Every doc belongs to one stratum
|
|
|
|
|
|
|
|
|
|
|
|
Decide the stratum before you write; it decides where the file goes and how
|
|
|
|
|
|
timeless it must read.
|
|
|
|
|
|
|
|
|
|
|
|
| Stratum | Kind of doc | Lives in |
|
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
|
| **E0 — orientation** | entry point, glossary | `docs/README.md`, `docs/glossary.md` |
|
|
|
|
|
|
| **E1 — architecture** | how the layers fit | `docs/architecture/` (the book chapters) + in-place stubs |
|
fix(cleanroom): F2+F3+F4-C+SEM-4s1 — lote mecánico, censos con guard, corpus documental y el close polimórfico de los pickers VIVO
F2 — lote mecánico (13 ítems):
- DEP-2 ogl eliminado (0 imports) · DEP-1 clsx inlineado como toClassString
propio + suite de contrato (props.test.ts; soma.md §12 cerrado).
- THM-7: los 5 selectores manuales de sema.md reescritos con semaSelector
(los ejemplos [data-toast-root] apuntaban a un part INEXISTENTE — la
deriva que el builder previene, demostrada en el propio doc).
- MOR-1 escape isomorfo + validación de attr-names en semaSelector + 9
tests (selectors.test.ts, matches() real con comillas/corchetes) ·
MOR-2 partMarkerAttr = única fuente compilador↔builder + test de paridad ·
MOR-3 _resetCompileCache borrado (0 usos).
- SOM-2 keydown continue en match sin handler + keyboardFixtureMorfo ·
SOM-1 no-await de handlers (censo async = 0; contrato V1 cumplido) + pin.
- SEM-2 trigger pre-attacha catch con logger (void trigger sin unhandled
rejection; throw intacto para awaiters) + pin · SEM-3 fallback muerto de
applyDominance → skip defensivo + timer tope de awaitExpression cancelado ·
SEC-1 adjudicado YA implementado (assertCssVariableValue desde 2026-05-11)
+ pin del path de VALOR.
- accordion → outline (§32; su outline:none dejaba CERO anillo en HCM) —
verificado en vivo · THM-6 radius-full 9999px · EID-4 recuentos 33.
F3 — censos con guard:
- SOM-3 cerrado: announcer + image-provider migrados a scheduler-preferred
(consumidores cableados: date/time-field vía soma.uix.timers; avatar/image
vía eidos.timers — verificado en vivo); guard de timers ENSANCHADO de
soma/components a TODO soma y pasado a EVIDENCIA (setTimeout exige
.schedule( en el fichero — layers/ y datetime/ escapaban del ámbito viejo).
- THM-5: R-4.7 nueva (válvula same-line /* important: <razón> */, escaneo
comment-blanked) + las 15 declaraciones anotadas con su razón + canon
recipe-contract §3/§4.
- SOM-4 adjudicado: el censo/guard YA existían (49 pins); knob/mask-field/
timeline pinneados (overrides documentados en call-site); media-player
Batch-4 (35 hits, cero renderProps) = único batch restante, registrado.
- THM-4 doctrinado en eidos.md §unused (comportamiento/composición =
legítimo; deuda = eje visual sin consumidor; hotspots por lotes).
F4-C — corpus documental (decisiones de usuario aplicadas):
- DOC-3: los 15 enlaces muertos resueltos (repoint a la edición FINAL
trackeada / des-link históricos) · docs:check I6-links WARN→ERROR.
- DOC-1: tabla «Build contract» MIGRADA a component-guide con estados
modernizados (A3–A5 → LIVE + guards de hoy); banners reapuntados; citas
de CANON/sema.md historificadas; lápida-redirect en el §13 del fósil.
- DOC-4: hold chain → holds.ts · FAQ event:* SUPERSEDED por signatures ·
gradient añadido a los DOS capstones (sextet real) · nota de paleta de
demo-authoring corregida (universalPaletteDecls + decisión THM-2 =
mecanismo universal como sucesor del tracker borrado).
- DOC-5/6: recuentos anti-frágiles datados · §4.11 dup → §4.12 · Known gaps
historificado · N-6/N-7 recuperadas de git (d68d2c45^) y canonizadas en
eidos.md §pickers · authoring E2 → canon/tsc.md · air-old des-linkado ·
EID-3 (placement) en la fila RTL · AUX-2 disabledDom documentado.
SEM-4 sesión 1 — el close polimórfico de los pickers, VIVO (D.11):
- Reconciliación: los morfos ya no declaran close (delegated al Popover,
de-dialoged 06-27); el agujero real era el cierre programático bypaseando
dismissWith → save/cancel/select eran perceptualmente SILENCIOSOS.
- Fix: PickerShellHandle.setPopoverDismiss + closeWith(cause) en los 5
providers (14 sitios; select/commit → 'save' = commit.save+fulfill,
cancel → 'cancel' = emerge; fallback raw para headless) + UN inyector en
el eidos PickerShell root (norma N-8). Picker genérico fuera a propósito
(ya suena commit-set/cancel por diseño S9).
- Verificado en vivo (date-picker): Done → close·commit·fulfill·active ·
Cancel → close·emerge · cierre real.
Gates: matriz 141/141 (los 6 morfos nuevos de la pista de texto paralela
también PASS) · contracts 38/38 · eidos 314 · sema 178 · morfo 94 ·
docs:check 0/0 con I6 en error · baseline propio 57.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 months ago
|
|
|
|
| **E2 — canon** | fixed vocabulary / contracts | `docs/CANON.md`, [`docs/canon/tsc.md`](./canon/tsc.md) |
|
|
|
|
|
|
| **E3 — decisions / RFC** | why a thing is built this way | `docs/decisions.md` + the RFC / design files |
|
docs(book): F7.5 (2/2) — COMPONENT_GUIDE moved; guides/ batch COMPLETE
src/uix/soma/COMPONENT_GUIDE.md (1449 L, English body) moved to
docs/guides/component-guide.md. The only Spanish passage — the
archetype-canon banner (2026-06-19) — translated in the move; the rest
is verbatim. Banner's ARCHETYPE_COHERENCE_AUDIT link reaches into src
(audit fossil, stays with the code); the checklist cross-link is now
the sibling ./completion-checklist.md and the 'soma/README s9' mention
now names architecture/soma.md (its post-F7.2 home). Corpus swept:
authoring + README E4 stratum rows (also stale THEMING_GUIDE name),
building-a-component phases 0/2, architecture/{soma-architecture s4/
s13-tree/s17, overview, morfo, active-architecture}.
F7.5 complete: docs/guides/ = component-guide, completion-checklist,
demo-authoring, component-audit. docs:check 0 errors, warns back at
the 11 baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 months ago
|
|
|
|
| **E4 — guides** | how to do a thing | `guides/component-guide.md`, `theming/guide.md` |
|
feat(packs+text): incorporate the animation collection — Ambient pack + text-effects family + docs
Two streams, split by what the animation touches:
STREAM A — decorative backgrounds → the pack tier
- arts/scene: a consolidated scene runtime ($scene) that owns, once, the
citizenship every ad-hoc background reinvented or skipped (frame loop,
off-view pause, DPR cap, mandatory reduced-motion, WebGL context
loss/restore, scene budget, teardown). SceneDom port (adom satisfies it),
webgl/webgl2/canvas2d drivers + a custom-pipeline extension (vertexShader +
draw + glContext.depth/dprCap) for real geometry (beam, particles, dither,
grid, eter, pixel-blast, hyperspeed). 32 effects as shared resources.
- src/packs/ambient: the first pack — <Ambient effect="…"> mounts a registered
effect; the P contract (P-1..P-6) guarded by scripts/packs-check.ts; colors
are token-aware (P-4). One-way dependency, removable-by-construction.
- resolveToken extended to semantic color slots (--color-{role}-{slot}) so
consumers resolve theme tokens to concrete colors (the P-4 half).
STREAM B — animations over real text → canon
- Six components (count-up + text-{gradient,circular,blur,focus,scramble}):
each a morfo + eidos recipe (where there's styling) + demo. CountUp is a
service component (counts through uix.format.numbers). The five Text* are
passive decoratives. Upgrades over the seeds: SR hardening (real text
visually-hidden + aria-hidden decoration), a11y fix (no fake role=button),
measurement discipline (cached rects via dom.measure, no reflow storm),
reduced-motion, ecosystem citizenship (eidos.dom/timers, no raw platform).
- MorfoElement gains 'p'.
DOCS
- docs/architecture/packs.md (pack tier, admission rule, P contract, Aura
promotion path); docs/decisions/design-text-effects.md (the family design
record) + indexed in decisions.md / README.md; glossary entries
(scene/Ambient/Aura/text effects); scene README custom-pipeline + authoring
bridge; motion-guide content-effects note; strata tables acknowledge packs.
Gates: component:audit 141/0/0 · docs:check 0/0 · scene tests 9/9 · packs:check
0/36 · check 0 own errors. Verified in browser (32 effects mount+compile;
6 text components SSR+hydrate, CountUp re-formats by locale live, TextGradient
resolves token stops to OKLCH via var()).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 months ago
|
|
|
|
| **E5 — module reference** | per-artifact docs | `src/arts/{name}/README.md`, `src/packs/{name}/README.md` (in-place) |
|
|
|
|
|
|
| **process** | hand-offs, snapshots, audits | `docs/process/` — ephemeral, never a source of truth |
|
|
|
|
|
|
|
|
|
|
|
|
Layer and module reference stay **in-place** next to the code. Cross-cutting
|
|
|
|
|
|
orientation, canon, decisions and process live under `docs/`.
|
|
|
|
|
|
|
|
|
|
|
|
## 3. Reference docs are timeless
|
|
|
|
|
|
|
|
|
|
|
|
E0–E5 docs must read as if written today, forever.
|
|
|
|
|
|
|
|
|
|
|
|
- **No session hand-offs inside a reference doc.** "Handoff 2026-05-14",
|
|
|
|
|
|
"Correcciones del engine (2026-06-01)", "Estado actual" blocks belong in
|
|
|
|
|
|
`docs/process/`, not at the top of a README. Extract them.
|
|
|
|
|
|
- **No fragile numbers or dates in prose.** "66 components", "as of 2026-05-15"
|
|
|
|
|
|
rot. Convert relative dates to absolute, and prefer pointing at the live
|
|
|
|
|
|
source over stamping a count.
|
|
|
|
|
|
- **Don't hardcode catalogs.** A list of "implemented components" drifts the day
|
|
|
|
|
|
the next one ships. Point at the directory tree / the morfos / the registry
|
|
|
|
|
|
instead.
|
|
|
|
|
|
|
|
|
|
|
|
## 4. One source per concern
|
|
|
|
|
|
|
|
|
|
|
|
If two docs would say the same thing, one **owns** it and the other **links** it.
|
|
|
|
|
|
|
|
|
|
|
|
- Don't duplicate content across docs (the transcription chain, the layer split,
|
|
|
|
|
|
"what soma is not" lived in 4+ places). Pick the canonical home; everywhere
|
|
|
|
|
|
else links it.
|
|
|
|
|
|
- Two docs about the same subject must have **distinct roles**, stated in their
|
docs(book): F7.5 (1/2) — checklist + audit guide + demo guide moved to docs/guides/
Three English guides moved verbatim (copy + link touch-ups, no
translation): COMPONENT_COMPLETION_CHECKLIST -> guides/
completion-checklist.md, COMPONENT_AUDIT_GUIDE -> guides/
component-audit.md, DEMO_AUTHORING_GUIDE -> guides/demo-authoring.md.
Tooling moved with its doc in the same pass: docs-check I5 now parses
the checklist at the new path (verified: 0 errors, rule tables found)
and component-audit.ts's two path strings updated. One reconciliation
in the audit guide's s5, applied as link-don't-copy: the copied v1
6-tab template list (stale vs the v2 9-tab guide it links, drawer
canary vs button) is replaced by a pointer to demo-authoring.md; the
domain canaries in s7 stay. demo-authoring's harness links now reach
into web/routes/uix/lib/ (the modules stay with the code); the deleted
pendiente_color_demos.md reference is marked TODO(reconcile). Corpus
swept: building-a-component (frontmatter related: + phases 6/8),
authoring, architecture/soma, theming/reference s5-parity,
testing-and-tooling, getting-started, README (E4 rows + component-audit
row added + two stale F7.3 paths in 'I want to' fixed). Remaining
warns = links to component-guide.md, which lands in F7.5 (2/2).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 months ago
|
|
|
|
headers. Examples that shipped: `architecture/soma` (onboarding) vs
|
|
|
|
|
|
`architecture/soma-architecture` (deep reference); `guides/component-guide`
|
|
|
|
|
|
(build steps) vs `guides/completion-checklist` (machine-audited acceptance).
|
|
|
|
|
|
- Never write a doc whose only content is re-exporting/redirecting another —
|
|
|
|
|
|
merge it, or make it a one-line pointer with a clear reason.
|
|
|
|
|
|
|
|
|
|
|
|
## 5. Frontmatter
|
|
|
|
|
|
|
|
|
|
|
|
Canon, index and reference docs open with YAML frontmatter:
|
|
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
|
---
|
|
|
|
|
|
title: <Doc title>
|
|
|
|
|
|
type: canon | index | guide | reference | notes
|
|
|
|
|
|
audience: human + agent
|
|
|
|
|
|
authority: <one line: what makes this authoritative or navigational>
|
|
|
|
|
|
status: current
|
|
|
|
|
|
# optional:
|
|
|
|
|
|
source: <where the content was extracted from>
|
|
|
|
|
|
related: { ... }
|
|
|
|
|
|
---
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Match the shape of [`CANON.md`](./CANON.md) / [`decisions.md`](./decisions.md).
|
|
|
|
|
|
|
|
|
|
|
|
## 6. Editing rules
|
|
|
|
|
|
|
|
|
|
|
|
- **Sections cited by number are load-bearing.** If a doc's `§N` is referenced
|
|
|
|
|
|
elsewhere in the corpus or in code comments, **do not renumber it**. To split
|
|
|
|
|
|
or shrink such a doc, use the **stub pattern**: leave a numbered pointer-stub
|
|
|
|
|
|
in the slot and move the content out (see THEMING → `TSC.md` / `THEMING_GUIDE.md`
|
|
|
|
|
|
/ `THEMING_NOTES.md`). Renumbering means sweeping every citation in the same
|
|
|
|
|
|
pass — only do that deliberately.
|
|
|
|
|
|
- **Fix links when you move content, and verify they resolve.** A wrong relative
|
|
|
|
|
|
path is silent (`soma/layers/GESTURES.md` vs the real `layers/gesture/GESTURES.md`).
|
|
|
|
|
|
- **Surgical.** Touch only what the task needs. Don't "improve" adjacent docs in
|
|
|
|
|
|
the same edit.
|
|
|
|
|
|
|
|
|
|
|
|
## 7. Language
|
|
|
|
|
|
|
|
|
|
|
|
- Target language is **English** (the migration is gradual; some layer docs are
|
|
|
|
|
|
still Spanish). When editing an existing doc, match its language — don't mix
|
|
|
|
|
|
two languages inside one doc.
|
|
|
|
|
|
- **Code comments are always English** (project-wide rule), including comments
|
|
|
|
|
|
inside fenced code blocks in docs.
|
|
|
|
|
|
|
|
|
|
|
|
## 8. Naming
|
|
|
|
|
|
|
|
|
|
|
|
- New decision/RFC/design docs: `rfc-{topic}.md` / `design-{subsystem}.md`
|
|
|
|
|
|
(kebab). The legacy `*_ENGINE_RFC.md` / `DESIGN_*.md` names are kept only
|
|
|
|
|
|
because they are cited as provenance across the code; don't add more in the
|
|
|
|
|
|
old shape.
|
|
|
|
|
|
- Markdown links, relative paths.
|
|
|
|
|
|
|
|
|
|
|
|
## Before you commit a doc
|
|
|
|
|
|
|
|
|
|
|
|
- [ ] Stratum chosen; file in the right place (in-place vs `docs/`).
|
|
|
|
|
|
- [ ] No canonical value copied — linked instead.
|
|
|
|
|
|
- [ ] No hand-off / dated-status / hardcoded catalog in a reference doc.
|
|
|
|
|
|
- [ ] Frontmatter present (for canon/index/reference).
|
|
|
|
|
|
- [ ] No `§N` renumbered that something cites; links verified to resolve.
|
|
|
|
|
|
- [ ] New doc wired into [`docs/README.md`](./README.md) if it's a top-level entry.
|
