Knowledge

Knowledge is decision authority, not workflow. An operator binds the smallest set of topics its decision needs and may emit no identifier outside that inventory. The three reading indexes below are copied from the tree.

UI knowledge

This tree holds the universal UI law shared by every published Grammar family, split into three groups by the operator that reads each one. It owns 153 stable live X-n laws (36 in composition, 68 in presentation, 49 in proof), plus five composition ids that are retired into COVERAGE-1 and the eleven retired UI- ids that now resolve to the proof topic rules that survived them, none of which are ever reused, together with observable selection conditions, ownership decisions, deterministic verdicts, and audit vectors. It is not an implementation or consumer cookbook. It does not own business facts, page copy, routes, permissions, artwork identity, product effects, or family material choices.

Runtime policy

• Canonical agent/runtime knowledge is the English .md file only.
• Same-stem .vi.md files are complete human-review mirrors. Never load, index, or cite them as runtime authority.
• Grammar operators resolve the smallest relevant canonical file and rule ID. Individual files omit per-topic routing metadata.
• Rule IDs are stable public knowledge addresses. Append the next sequential PREFIX-n; never renumber, reuse, or silently change the meaning of an existing ID.
• Knowledge owns invariant decisions and audit vectors, not implementation status, migration plans, workflows, operator DAGs, or task orchestration. Current capability/debt belongs in plans and audits.

Grammar binding

@grammar/common is the public authority for props, semantics, renderer anatomy, state, accessibility, composition, and universal implementation. A family-selected application imports exactly the selected family stylesheet; that stylesheet imports Common. Direct @grammar/common/styles.css consumption is reserved for intentional familyless Common usage and isolated test harnesses. An application must not import both paths for the same rendered tree.

A visual family is a props-compatible scoped overlay declared through defineGrammarFamily. It may replace a known Common renderer with the exact compatible props or add a non-colliding extension; its stylesheet is scoped by data-grammar-family. It must preserve Common meaning, state behavior, accessibility, ownership, and substitutability.

Business/application code selects one family and supplies domain content, data, permissions, handlers, and verified state. Application CSS may own page canvas, product layout/content/media, and placement through public extension points. It must not reach through, rebuild, or override Common-owned anatomy, spacing, semantics, state, focus, or variants. Family documents record overlay choices and conformance evidence; they never duplicate or redefine these universal laws. A missing reusable capability is a Common gap, not permission for product-local anatomy or a family-specific universal rule.

Groups

A topic lives with the operator that reads it. A topic no operator reads has no reason to exist.

The test that places a topic is whether reading source answers it. A spacing value is readable from a class, so it is presentation. The number of dominant actions is settled before any tree exists, so it is composition. Whether keyboard order matches visual order needs a running page, so it is proof.

Code conventions for the source that produces all of this live in patterns/. Family realization lives in grammars/.

Rule binding architecture

Knowledge defines what a rule means; it does not hard-code which current DOM instance passes it. A Common reusable exposes stable component, slot, and relationship anchors. A co-located or generated binding registry maps those anchors to rules with at least:

• a stable binding ID and version;
• ruleId;
• exact target slot or between-slot relationship;
• the when variant, state, or composition selector;
• the expected owner anchor.

The registry never duplicates the rule’s metric or behavior. Applications do not hand-author rule arrays, and no markup can label itself as passing. The auditor resolves bindings from stable DOM anchors, collects rendered evidence, and records rule IDs and findings in the audit result. Unknown rule IDs, missing slots, stale anchors, and orphan bindings fail validation. DOM outside a registered reusable may be selected by semantic inspection, but it cannot receive PASS without the same owner and runtime evidence.

A contract claim is the one exception, and it is not a self-assessment. A rule-binding operator may emit data-contract on a node it resolved, as a space-separated list of the identifiers that node claims to satisfy. The claim states an intention so the auditor can contradict it: a node claiming GAP-4 while the computed gap is 1.5rem is a finding, a node carrying spacing that claims nothing is an unowned value, and a claimed identifier absent from published knowledge fails validation. A claim never carries a verdict, score, or PASS, and a hand-written one is invalid because only the operator’s receipt makes it verifiable. Grammar emits the same claim on the elements that realize a relationship it owns, the rows of each topic’s “Common already owns” table, so a Grammar-internal value is never an unowned value and the resolver never re-claims those nodes. The receipt remains the durable record, so the attribute may be stripped from a production build without weakening any audit.

Canonical verdict model

Base verdicts are exactly: PASS, COMMON_CAPABILITY_MISSING, COMMON_IMPLEMENTATION_GLITCH, FAMILY_OVERRIDE_GLITCH, APP_REIMPLEMENTATION, APP_OVERRIDE, APP_WORKAROUND, PROOF_MISSING.

Cause tags are exactly: VALUE_DRIFT, VENDOR_LEAK, WRONG_OWNER, OFF_SCALE_VALUE, DOUBLE_OWNER, PHYSICAL_SIDE_DRIFT, STATE_OR_VIEWPORT_DRIFT.

Evaluate capability, isolated Common output, family delta, app delta, then owner/state evidence. One finding contains one base verdict and zero or more cause tags. Multiple failed layers produce linked findings; they are not collapsed into a composite base verdict or suppressed by first-match logic. PASS is valid only when no failure finding exists.

Source: knowledge/ui/INDEX.md.

StarCi Core Grammar — reading index

This branch documents one visual family: StarCi Core, and the taste that directs how it is composed. Universal UI law remains canonical in knowledge/ui; this branch maps those X-n rules to the live Core family and records the idioms StarCi actually builds with. It never re-narrates renderer anatomy — DNA, generated from the package, already says what exists and what each renderer owns.

Authority chain

knowledge/ui X-n → @starci/grammar/common props/anatomy/state → @starci/grammar/core DNA and scoped CSS → product adapter

• Common owns public renderers, props, semantic DOM, accessibility, presentation states, universal spacing, COMMON_GRAMMAR_COMPONENTS, and defineGrammarFamily.
• Core is a sibling family with id core; CoreGrammarRoot installs data-grammar-family="core", and the @starci/grammar/core entry re-exports every Common renderer, so a Core consumer imports from one entry.
• Feature code owns domain facts, routes, copy, permissions, persistence, and effects.
• Product names such as Learn, Console, Dashboard, Navbar, or Course never become Grammar identities.

Read order

0. DNA — generated from the package: what exists. Prime a direction agent with this file.
1. Idioms — how StarCi composes what exists, each idiom evidenced at least twice in the live blocks.
2. Playbook — which idiom sequence a business shape asks for, and what a supplied reference may contribute.
3. Family and DNA — the visual family’s own identity, tokens, CSS direction, theme binding, and the one gap table the whole family publishes.

Read 0 through 2 to decide what to build; read 3 when a row raises a question about the family itself. How the package is consumed in code (imports, one family root, forbidden clones) is FE-IMPORTS-5 and FE-IMPORTS-7 in knowledge/patterns/fe.

Review gates

A valid change has no renderer import from @starci/grammar/core, no Common CSS import of Core CSS, no feature-named component in Grammar, no duplicated X-n law, and no EN/VI drift. Core-specific claims must resolve to live source or be named as a gap.

Source: knowledge/grammars/starci/INDEX.md.

Frontend code patterns

knowledge/ui/ decides what the interface must be: which Grammar object renders, which gap, which tone. knowledge/patterns/fe/ decides how the code that produces that interface is written: where a unit lives, what its files are called, how a component function is shaped, where a class string sits, how a failure is represented, and where the spec goes. A pattern rule never chooses a visual; a ui/ rule never chooses a file name. Every rule below was extracted from the reference application (src/) and its Grammar package (packages/grammar/src/) by opening files and counting, and each table cites the files it was read from. Where the code is split, the file records the dominant variant with its count instead of legislating.

Catalog

Sources

Application: the reference application’s src/ (976 non-spec TypeScript files, 497 specs). Grammar package: its packages/grammar/src/. Lint canon consulted for rule names only: @starci/eslint-canon-fe as installed under node_modules.

Source: knowledge/patterns/fe/INDEX.md.