go
/
svelte-kit-vice
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(reconciliation): degrade GUIA_IMPLEMENTACION_SEMAUIX to historical seed

Browse Source 
Phase 1b of PLAN-docs-reconciliation (fable_audit D2). The guide contradicted
the code in >=5 verified points while CLAUDE.md declared it authoritative.
Decision: degrade, don't reconcile — frontmatter (status: historical) + banner
pointing at docs/CANON.md + code as the ruling sources, and surgical fixes on
the dangerous points only:
- s2: real inventory is 9 roles (tertiary) with --color-{role}-{slot} naming;
  pointer to THEMING s4 + THEME_BASE_COLOR_ROLES.
- s4.1: table annotated as doctrinal; Dialog row now records the implemented
  emerge (open/close polymorphic, no shift in allowedFamilies).
- s5.3: phantom defaultSemantic shape replaced by the implemented additive
  allowedFamilies (real dialog.ts excerpt; LIBRO_VARIACIONES D.11).
- s6.2: diverged holds table replaced by pointers to SEMA_MAP + holds.ts.
- s14: marked historical (migration plan already executed).
CLAUDE.md citations untouched (own deferred pass).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
menubar-v4-safe
dev 3 months ago
parent 925508c764
commit 74b23b5871
1 changed files with 73 additions and 52 deletions
Show Stats Download Patch File Download Diff File

125
src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md
Unescape View File

@ -1,11 +1,26 @@
---
title: Guía de implementación — Semántica perceptiva en UIX
type: notes
audience: human + agent
authority: historical seed — superseded by docs/CANON.md + code; kept for the Spanish narrative
status: historical
---
# Guía de implementación — Semántica perceptiva en UIX
> **Estado: semilla histórica, NO autoritativa.** Este documento fue la guía
> fundacional de la migración semántica (2026-05). El canon vigente es
> [`docs/CANON.md`](../../docs/CANON.md) + el código (`SEMA_MAP`, `holds.ts`,
> los morfos); las desviaciones y extensiones registradas viven en
> [`LIBRO_VARIACIONES_Y_EXTENSIONES.md`](./LIBRO_VARIACIONES_Y_EXTENSIONES.md).
> Se conserva por su narrativa en castellano. Donde este texto discrepe del
> canon o del código, **el canon y el código ganan**. (CLAUDE.md aún lo cita
> como autoritativo; esa cita se actualizará en el pase diferido de CLAUDE.md.)
## De la teoría del libro a la arquitectura del framework
Este documento traduce las decisiones del libro *Semántica perceptiva de la interfaz* a la arquitectura UIX (Morfo/Soma/Sema/Eidos). No repite la teoría — la convierte en contratos, vocabularios, reglas de resolución y convenciones técnicas.
Documento autoritativo para toda migración, wrapper nuevo o extensión de componente.
---
## 1. Vocabulario canónico corregido
@ -105,6 +120,14 @@ export const SEMA_VERBS = {
## 2. Sistema de 8 tokens de color
> **Vigente**: el inventario real es de **9 roles** — se añadió `tertiary`
> (jerarquía) — y los slots CSS reales son `--color-{role}-{slot}`
> (`solid`, `text`, `bg`, `border`, …), no `--color-{role}-element`.
> Fuente: [`eidos/THEMING.md`](../uix/eidos/THEMING.md) §4 +
> `THEME_BASE_COLOR_ROLES` (`src/uix/eidos/themes/base.ts`). La doctrina de
> dos ejes (jerarquía vs intent) que sigue es la vigente; los nombres
> concretos evolucionaron.
### 2.1. Los 8 valores
Dos ejes ortogonales:
@ -154,20 +177,11 @@ Un componente recibe dos props ortogonales con prioridad clara:
### 2.4. Tokens CSS por theme
Cada theme define los 8 tokens:
```css
:root {
--color-primary-element: ...;
--color-secondary-element: ...;
--color-neutral-element: ...;
--color-affirm-element: ...;
--color-fulfill-element: ...;
--color-risk-element: ...;
--color-threat-element: ...;
--color-loss-element: ...;
}
```
Cada theme define los roles; el inventario y los nombres de slot reales
(`--color-{role}-{slot}`) viven en [`eidos/THEMING.md`](../uix/eidos/THEMING.md)
§4 y en el generador (`DEFAULT_COLOR_ROLE_SLOT_STEPS`,
`src/uix/eidos/lib/render-css.ts`). El naming `--color-{role}-element` de la
versión original de esta guía nunca llegó al código.
El theme decide hue/sat/lightness por marca. El componente solo declara qué token leer.
@ -238,13 +252,21 @@ La estética tiene libertad dentro del rango que la semántica permite. Un affir
### 4.1. emerge vs shift
> **Tabla orientativa (doctrina del libro), el morfo manda.** La
> implementación asignó `emerge` a los overlays Dialog / Drawer / Popover:
> sus morfos declaran `open`/`close` con `family: 'emerge'`, y el `close`
> polimórfico admite `allowedFamilies: ['emerge', 'commit', 'signal']` — sin
> `shift` (ver `src/uix/morfo/components/dialog.ts` y
> [`LIBRO_VARIACIONES`](./LIBRO_VARIACIONES_Y_EXTENSIONES.md) D.11). Ante
> cualquier duda, la familia real de un componente es la de su morfo.
| Componente | Familia | Razón |
|---|---|---|
| Dropdown | emerge.open | aparición local, no cambia marco |
| Popover | emerge.open | aparición anclada |
| Tooltip | emerge.present | información auxiliar |
| Accordion | emerge.expand | contenido contenido |
| Modal / Dialog | shift.enter-mode | cambia marco, captura foco, subordina fondo |
| Modal / Dialog | emerge.open (implementado) | el libro lo doctrina shift.enter-mode; el morfo declara emerge |
| Command Palette | shift.enter-mode | cambia régimen operativo |
| Edit mode | shift.enter-mode | cambia qué puede hacerse |
| Wizard step | shift.step | avanza en proceso |
@ -307,28 +329,35 @@ No todo evento debe ser `pre` como el Toast dismiss. Contact debe ser `post` (in
### 5.3. Capacidad semántica vs evento fijo
Morfo puede declarar capacidad semántica cuando el componente soporta varios eventos según contexto:
Morfo puede declarar capacidad semántica cuando el componente soporta varias
familias según contexto. El shape implementado es **aditivo** — el evento
declara su semántica concreta como default y `allowedFamilies` habilita el
override (el shape `defaultSemantic` de la versión original de esta guía se
descartó; ver [`LIBRO_VARIACIONES`](./LIBRO_VARIACIONES_Y_EXTENSIONES.md)
D.11). Del morfo real del Dialog:
```ts
events: [
{
name: 'close',
semantic: {
allowedFamilies: ['shift', 'commit', 'emerge'],
defaultSemantic: { family: 'shift', verb: 'exit-mode' }
family: 'emerge', // default
verb: 'close',
target: v.partRef('content'),
sequence: 'pre',
persistence: 'transient',
allowedFamilies: ['emerge', 'commit', 'signal']
}
}
]
```
El provider concreta:
El provider concreta con un override validado contra `allowedFamilies`:
```ts
// Dialog con cambios sin guardar
semantic: { family: 'commit', verb: 'discard', intent: 'loss' }
// Dialog informativo
semantic: { family: 'shift', verb: 'exit-mode' }
runtime.trigger('close', {
semantic: { family: 'commit', verb: 'save', intent: 'fulfill' }
});
```
---
@ -351,32 +380,17 @@ persistence: 'transient' | 'untilAction' | 'untilFix' | 'stateBound'
### 6.2. Holds por familia e intent
```ts
const SEMA_HOLDS = {
contact: 120,
emerge: 180,
shift: 240,
commit: {
neutral: 200,
affirm: 180,
fulfill: 280,
risk: 240,
threat: 240,
loss: 240
},
signal: {
neutral: 240,
risk: 'untilFix',
threat: 'untilAction',
loss: 400
},
handle: {
pick: 120,
drop: 180
},
sustain: 'stateBound'
};
```
Los valores canónicos viven en el código — no se copian aquí (regla
anti-drift de [`docs/authoring.md`](../../docs/authoring.md)):
- **Holds base por familia**: `SEMA_MAP.families[F].hold` en
`src/uix/sema/sema-map.ts`.
- **Tabla de referencia holds-por-intent**: `SEMA_HOLDS_BY_INTENT` en
`src/uix/sema/holds.ts` (referencia doctrinal, NO auto-aplicada — el
default conservador es `transient` y cada morfo declara su `persistence`).
La tabla numérica que ocupaba esta sección divergió del código en semanas;
consulta siempre las dos fuentes de arriba.
### 6.3. Sustain no tiene hold fijo
@ -665,6 +679,13 @@ mantiene un segundo API flat con snippets que duplique el compound.
## 14. Plan de migración
> **Histórico — plan ya ejecutado.** Las cinco prioridades y la tabla de
> componentes de esta sección se completaron durante los sprints 2026-05
> (vocabulario, tokens, holds/persistence, sequence, a11ySemantic, y la
> migración eidos completa). Se conserva como registro del arco de la
> migración; el estado real de cada componente lo da
> `npm run component:audit`, no esta tabla.
### 14.1. Prioridad 1 — Vocabulario
1. Renombrar `alert` → `signal` en SEMA_FAMILIES

Write Preview
Loading…
Cancel
Save

Powered by TurnKey Linux.