How to Read Reference Implementations

Existing Prototype implementations are important evidence, but they are not the highest authority. Use this reading order:

applicable P lifecycle and criteria
→ related decisions / contracts / inheritance
→ mapped T cases and executable paths
→ implementation and focused tests
→ exports, CLI, docs, demo

When implementation conflicts with an applicable entity, identify drift first. Do not silently change protocol meaning because “the repository currently does it this way.”

Search by name, ID, or criterion:

rg -n "<prototype name|entity id|criterion id>" spec packages/prototypes apps/www internal/records

Confirm:

• whether the P entity is draft, active, deprecated, or removed;
• which criteria apply to the current problem;
• how direct Prototypes, authored asHooks, and Parts are cataloged;
• inherits.prototypes, dependencies, and related decisions; and
• which executable tests the T cases map.

Legacy contracts and records can explain background. They cannot override an existing applicable spec entity.

Button is a relatively small vertical slice:

• P-BASE-BUTTON;
• T-BASE-BUTTON-0001;
• button.proto.ts; and
• packages/prototypes/base/test/as-button.test.ts.

Trace criteria into props, state, accessibility, events, exposes, and absence guarantees instead of recording only the order of API calls.

Toggle provides another independent Base protocol for comparison:

• P-BASE-TOGGLE and T-BASE-TOGGLE-0001; and
• toggle.proto.ts.

Button and Toggle both having authored asHooks does not permit one protocol to consume the other’s protocol-specific hook.

Tabs requires Root and Parts together:

• P-BASE-TABS plus the List, Trigger, Content, and Indicator P entities;
• the corresponding T-BASE-TABS-* entities;
• shared.ts;
• root.proto.ts;
• list.proto.ts;
• trigger.proto.ts;
• content.proto.ts; and
• indicator.proto.ts.

Trace owners, context facts, anatomy claims, collection and focus responsibilities, and mapped tests. File count alone does not prove a correct boundary.

Shadcn Button is a compact Base-projection example:

• P-SHADCN-BUTTON and T-SHADCN-BUTTON-0001;
• inherited P-BASE-BUTTON criteria;
• Shadcn Button source; and
• packages/prototypes/shadcn/test/button.test.ts.

Verify that:

• the derived P declares only its delta;
• implementation calls the owning Base asHook;
• rules depend on inherited protocol states instead of making host selectors a second truth;
• unsupported upstream APIs and absence assertions are recorded; and
• package exports, CLI facades, website demos, and the P/T surface agree.

Shadcn Switch and Tabs offer differently sized projections, but always begin from their own P/T graph rather than mechanically copying directory structure.

After source and tests, inspect:

• package subpaths and root exports;
• CLI registry and generated facades;
• component-preset or style-token closure when applicable;
• bilingual docs and a real public-package demo;
• Web Component, React, and Vue Web evidence; and
• generated workspace and Agent projections.

This distinguishes “implementation exists” from “the contribution forms a consumable, reviewable closure.”

The Base Button, Toggle, Tabs, and Shadcn Button entities referenced here are currently draft. Learn from their ownership and evidence structure without widening current implementation details into uncataloged stable guarantees.

• Maintaining an Existing Prototype
• Projecting Base into a Design Language
• Implementing an Approved Base Semantic Slice