dotfiles/claude/memory/feedback-scss-audit-as-timeless-way-of-building.md

name, description, type, originSessionId, permalink

name	description	type	originSessionId	permalink
SCSS audit method — as Alexander designed The Timeless Way of Building	Steward's articulation 2026-05-08 of what the code-shape audit must achieve. Method (spec-compliance test + performative-gap test) and aesthetic standard (Alexander's flow between large and small patterns). Load-bearing for the audit and for all future SCSS work.	feedback	f765b329-ea05-4a61-8ada-9bf72971b299	claude-memory/feedback-scss-audit-as-timeless-way-of-building

SCSS audit — as Alexander designed The Timeless Way of Building

Authorized 2026-05-08 (steward verbatim, full):

"When we do the audit, we need it to achieve many things obviously, but one major thing is that the scss must comply with spec, and if there is scss that has no spec, we need to determine if that represents a genuine gap, or if it is performative. I want the scss, once 'finished' to resemble The Timeless Way of Building, the way Alexander designed the book: The large patterns flow into the smaller and vice-versa. That simplicity and elegance allows for complexity which is generative — and it is beautiful."

The method (the audit test)

Two tests applied to every selector and every rule:

1. Spec-compliance test. Does this rule comply with the AldineXXI spec? If yes, keep. If no, fix to comply or escalate the divergence to spec-amendment.
2. Spec-presence test. If the rule has no spec sanction, is it a genuine gap (the spec needs to extend) or performative (the rule needs to be retired)? The contamination problem applied to typography: the question to ask of every unspecced rule is "what is its self-assessment, and is that assessment honest?"

.whisper is the example that surfaced the test (2026-05-08): no spec sanction, doing two jobs (body-content voice-volume + apparatus-metadata), one of which (Job A) was performative-by-the-steward's-own-diagnosis, the other (Job B) revealed a real spec gap (apparatus colour) which was filled by §VII.e.

The aesthetic standard (the audit goal)

The Timeless Way of Building, the way Alexander designed the book.

What Alexander did with the book itself is the model:

• The large patterns (the chapter-level argument: the quality without a name; the gate; the way) flow into the smaller patterns (the individual numbered patterns 1-253 in A Pattern Language; the typographic and structural decisions inside each chapter).
• The smaller patterns flow back upward and shape the large.
• Simplicity and elegance at every scale — and that simplicity is what permits generative complexity. The simplicity is not the achievement; the generative complexity is. The simplicity is the precondition.
• It is beautiful — and the beauty is load-bearing, not decorative. It is what tells the reader the system is right.

For ARC's SCSS this means:

• Variables flow into mixins flow into selectors flow into utilities with no parallel mechanisms, no dead code, no rule that does what another rule already does, no value hardcoded where a token would carry it.
• Spec sections flow into SCSS partials legibly. A reader of the spec should be able to find the corresponding SCSS without searching; a reader of the SCSS should be able to find the spec it implements without searching.
• The large patterns (the §VII apparatus principle, the §III colour system, the §II spacing scale, the §I typographic core) are visibly load-bearing in the small selectors. The §VII.e principle ("apparatus differentiates by form, not luminance") reads through every apparatus rule because the rule simply uses --fg and the form-levers; nothing argues about it locally.
• The small patterns (a single selector's specific rendering) report back upward — when a small rule wants to break the pattern, that's signal to revisit the large pattern, not signal to add an exception.
• Generative: when the next type is added, or the next apparatus is added, or the next register is added, the existing pattern carries it without strain. This is the test of whether the simplicity is real: does it generate?
• Beautiful: not as polish but as integrity. The SCSS reads as inhabitable architecture, the way the spec reads as inhabitable typography.

How to apply during the audit

When auditing a selector or rule:

1. Find the spec section that governs it. (If none: spec-presence test.)
2. Verify the rule complies. (If not: fix or escalate.)
3. Check whether the rule duplicates or parallels another mechanism. (If so: consolidate to a single rule per the one rule, one place principle locked 2026-05-07.)
4. Check whether the rule hardcodes a value that should be a token. (If so: substitute the token.)
5. Check whether the rule names what it does, or whether it has accumulated a comment that promises behaviour the rule no longer delivers. (Stale comments are themselves contamination — name what is.)
6. Ask: when a future ARC type or apparatus is added, will this rule carry it without strain? If not, the rule is too specific or too parallel; revisit.

The audit is not a sweep-for-cleanup; it is a return to spec. Each return strengthens the whole.

Cross-reference

• AldineXXI §VII.e Apparatus Colour (2026-05-08) — first amendment landed under this method; surfaced from .whisper audit.
• AldineXXI §XIV Governance — the change protocol the audit operates under.
• ~/CLAUDE.md Prime Directive — do things once, correctly, with lasting integrity. Choose what is proportionate, fitting, and durable. The audit is the Prime Directive applied to ARC's SCSS.
• The Timeless Way of Building (Christopher Alexander, 1979) — the model.
• A Pattern Language (Alexander et al., 1977) — the worked example of large→small flow.
• Drift patterns named 2026-05-07: hardcoded-value-not-theme-aware, parallel-mechanism-where-one-rule-fits — both subsumed under the audit method above.