# Shared Reality Text version of the Shared Reality website (https://sharedreality.fraukebrinkmann.com/), version 0.2.1. Generated from the same page sources as the website; the component pages and their specifications are on the website and in Storybook (https://sharedreality.fraukebrinkmann.com/storybook/?path=/docs/introduction--docs). Shared Reality · Why It Matters ## One shared product reality. Multiple technologies. Governed by design. Shared Reality shows how product architecture, design infrastructure, accessibility, AI-enabled experiences and technical governance work as one coherent system, rather than as fragmented decisions spread across teams, technologies and products. From architectural vision to working infrastructure. ### The challenge Large product landscapes rarely run on one technology. They grow across applications, teams, platforms, devices and generations of software. Every team interprets the same requirements again. Colours, states and behaviour drift apart, decisions get lost when teams or technologies change, and AI-assisted development multiplies local conventions. The result is duplicated effort, inconsistent products and missing traceability, which is costly in regulated markets. Consistency is not only a question of how a product looks. Shared Reality works on three connected levels: semantics, the meaning of elements, states and actions; UI architecture, how that meaning is represented and technically implemented; and behavioral experience, learnable orientation, interaction hierarchy and predictable behaviour. Together, they establish a coherent cross-product experience architecture: one that people understand, teams reuse and different technologies can implement. Shared definitions make variation possible without making product meaning arbitrary. ### Decisions & Impact The key decisions, ordered by their impact on people, teams and the organisation, with the challenge each one addresses and where to see it working. #### People keep their orientation when they move between products Shared conventions for orientation, navigation and top-level interactions stay recognisable while domains change, so learned conventions carry over. Domain-specific workflows can differ. ##### The challenge Products of one company look and behave differently, so people relearn orientation in every application. ##### The decision TwistLock defines the product-level conventions: identity, navigation, orientation and predictable top-level interaction behaviour. Each domain supplies its content and its workflows. See it: TwistLock → Overview #### People can tell which level an action belongs to before they act Main actions and central filters are recognisable in every product. Teams decide the hierarchy once instead of per screen. ##### The challenge When every control looks alike, the main action of a screen cannot be told apart from a minor one. ##### The decision Signature Components mark the top level of interaction; standard components handle everything below. The meaning comes from consistent use, placement, behaviour and visual distinction, governed by usage rules. See it: Signature Components → Overview · Style Guide → Component Usage #### Recurring situations are solved once The same structure and behaviour in every product; variants without copies. ##### The challenge Every product builds its own version of the same situation, such as a form or an assistant, with its own structure and behaviour. ##### The decision Compositions apply this order to recurring situations of use: one implementation with a small, typed configuration. The product decides its requirements; the Composition keeps the structure. See it: Compositions → Overview · Compositions → Patient Details #### AI-generated content has an explicit, recognisable identity People can tell whether a message comes from AI, a person or the system, wherever the AI Assistant is used. ##### The challenge Users cannot tell AI content from human content. ##### The decision The AI Assistant separates who sends a message from where its content comes from. A missing origin is shown, never assumed. See it: Compositions → AI Assistant #### New ideas are tested before the system has to grow Teams develop the best experience first and decide afterwards what stays product-specific and what becomes part of the shared design system. The design system does not have to grow with every idea before anyone knows whether it works. ##### The challenge AI tools build interfaces quickly, but with other libraries and conventions. Without a rule, experiments either wait for the system or slip into products and erode it. ##### The decision Exploration is a regular innovation mode: AI tools may choose any UI and technical approach, starting from the brand and the tokens. Its results can be discarded, continued as a product-specific solution within the rules, or proposed for adoption into the design system. See it: Shared Reality → The Idea (AI governance) #### Accessibility is part of every change Accessibility requirements are documented once and applied in the shared components, so problems are found while building, not at the end. ##### The challenge Accessibility is checked late, product by product, and corrected at high cost. ##### The decision Accessibility is a shared rule set based on WCAG 2.2: semantic structure and accessible names, keyboard and visible focus, labels and errors, status not by colour alone, target size, announcements, reflow and reduced motion. Contrast, for example, is checked automatically in six colour schemes; keyboard and screen-reader review stays a manual step. See it: Style Guide → Accessibility · Foundations → Colors #### One shared definition supports multiple implementations A colour role is defined once, and every integrated library reads it. A mismatch fails before it is merged. ##### The challenge UI libraries drift apart; colours and states are maintained twice and differ from product to product. ##### The decision Design tokens define every colour role once; all integrated libraries read from that source. See it: Foundations → Colors · Foundations → All Tokens #### Architectural decisions remain traceable Audits and onboarding can see why something is the way it is, and who decided. ##### The challenge Decisions disappear when teams, products or technologies change. ##### The decision Architecture decisions are recorded with their context and consequences. Every change runs the full automated verification, including accessibility checks. See it: Shared Reality → The Idea (Governance and verification) ### Explore the system - **Shared Reality**: Why it matters, the idea, where its definitions live and how it is governed. - **Foundations**: Colours, typography, spacing, corner radius, shadows, icons, all tokens and brand. - **Style Guide**: Visual and usage rules, component usage and accessibility. - **Experience**: How people interact with a product, from component behaviour to interaction patterns. - **Components**: The standard MUI components with the Shared Reality theme, grouped as in the MUI documentation. - **TwistLock**: The recognisable outer product chassis: AppBar, Sidebar Navigation, Bottom Bars and Action Bar. - **Signature Components**: Purpose-defined UIs, each implemented as a single reusable component. - **Compositions**: Purpose-defined UI/UX assembled from multiple components, including Configurable Modules. - **Extended Components**: Additional UI components integrated into Shared Reality. ### My role: end-to-end architecture and ownership Frauke Brinkmann UX Lead & Product System Architect Enterprise Product Architecture · Design Infrastructure · AI-Enabled Product Development · Governance I conceived, architected and built Shared Reality: from the system concept and experience architecture to design infrastructure, frontend implementation, accessibility engineering, automated verification and governance. #### What this brings to a company - Scalable product infrastructure: Shared definitions and reusable experience structures enable coherent product evolution across domains and technologies. - Reduced duplication and implementation complexity: Teams reuse established semantics, interaction conventions and components instead of independently rebuilding them, and build on a decided hierarchy instead of deciding it per screen. - Governed quality and change: Accessibility rules, documented architectural decisions and automated verification support controlled, traceable product evolution. - Trust and orientation: Recognisable structures and predictable behaviour across the products of a company. - Lower operating risk: A recognisable interaction hierarchy helps people see which level an action belongs to before they act. - Better alignment across disciplines: Semantics, UI architecture and behavioral experience give product, design, engineering and compliance one shared vocabulary. - AI with control: AI content is transparent, and AI-assisted development stays under human review. - End-to-end product architecture leadership: Connecting product strategy, UX, engineering and governance through coherent architectural decisions, reducing coordination overhead and keeping design intent intact across teams. The differentiator: I design cross-product experience architectures that people understand, teams reuse and different technologies can implement, and I take them from system vision through implementation, verification and governed evolution. #### About Shared Reality Shared Reality is an independently conceived, architected and developed design system, informed by my professional experience in complex enterprise and regulated healthcare environments. Original employer-owned interfaces and confidential implementation details are not reproduced. Healthcare-related demonstrations are illustrative and not for clinical use. --- ## The Idea Shared meaning and behaviour. Different implementations. Shared Reality approaches the design system as governed Product Experience Infrastructure for healthcare software. Its central architectural decision is to separate the definitions that must remain consistent across a product system from the technologies that implement them. This allows different applications and frameworks to share product UI meaning and specified behaviour without requiring identical components or source code. ### 1. The challenge is not component reuse alone A shared component library can standardise interfaces within one technology stack. But enterprise product landscapes often contain React applications, Angular applications and legacy systems that cannot simply adopt the same components. When each implementation interprets design rules, interaction states and component behaviour independently, inconsistencies emerge. Similar interfaces can begin to communicate different meanings or behave differently. AI-assisted development can accelerate this fragmentation when generated interfaces reproduce local implementation conventions without a shared architectural reference. The underlying challenge is therefore not only to reuse components. It is to preserve product meaning and specified behaviour across implementation boundaries. ### 2. Shared rules. Different implementations. Shared Reality establishes a common reference through explicit, versionable design definitions: - Semantic foundations and design tokens - State and visual rules - Component specifications - Interaction and Experience patterns - Documented responsibilities and verification expectations These definitions describe what must remain consistent. Individual technologies determine how to implement them. A component does not need to share the same source code across frameworks to preserve its meaning, appearance and behaviour. Shared definition ≠ shared implementation. Implementation can vary. The relationships between meaning, state, behaviour and representation must remain coherent. #### The architectural boundary Framework-independent definitions do not mean framework-independent executable components. A React component cannot simply be reused as an Angular or C++ component. Instead, each implementation must reproduce the relevant shared rules and verify the resulting behaviour. This distinction prevents framework independence from becoming an unsupported claim of universal technical compatibility. ### 3. Three levels: semantics, UI architecture and behavioral experience Three connected levels; behavioral experience is one of them, not the umbrella term for the whole architecture. | Level | Answers | In the Explorer | | --- | --- | --- | | Semantics | What does an element, a state or an action mean, and which meaning must stay the same across applications and technologies? | Foundations → All Tokens, state contracts, component specifications | | UI architecture | How is that meaning represented and technically implemented: tokens, components, layouts and states? | Foundations, Components, Style Guide | | Behavioral experience | How do people learn orientation, interaction hierarchy and predictable behaviour, also when they change domain, product or device? | Experience, TwistLock, Signature Components, Compositions | Behavioral experience works at three scales. TwistLock creates continuity at product level: orientation, navigation, identity and predictable top-level interaction behaviour, while domain-specific workflows can differ. Signature Components create a recognisable hierarchy of interaction within that product world. Compositions apply these foundations to recurring situations of use. A Signature Component does not signal its level by appearance alone. The meaning becomes learnable through consistent use, placement, behaviour and visual distinction. That is why its use is governed by rules, not left to taste. #### Semantic foundations Design tokens and semantic roles define the meaning and application of colours, typography, spacing and other visual foundations. Primitive values provide reusable building blocks. Semantic roles describe their usage. Framework mappings translate those roles into a particular implementation. These layers should remain distinguishable so that technical mappings do not silently redefine product meaning. Foundations → Colors Foundations → All Tokens #### State and visual rules Interaction states depend on more than individual colour values. Opacity, tonal variation, overlays and surface context influence the rendered result. Relevant rules must be understandable beyond the framework that currently implements them. For example, MUI calculates certain state treatments through opacity and palette relationships rather than through a separate colour token for every component state. A different implementation may use another rendering mechanism while still preserving the specified visual and behavioural result. Documented values say whether they are a Shared Reality rule, a value inherited from MUI or an implementation detail, so another implementation knows what to reproduce. Foundations → Colors Foundations → Shadows #### Components and Experience Component specifications define reusable UI building blocks. Experience rules describe how components are used, interact and remain consistent across product situations. Signature Components and Compositions extend the shared library where a defined purpose requires them. Component behaviour and broader interaction patterns remain distinct: a component can provide its own focus, selection and error behaviour, while a product-level interaction pattern coordinates multiple components within a task. Style Guide → Component Usage Experience → Interaction Patterns Signature Components Compositions → Overview #### Verification and governance Versioned definitions, implementation checks and human review help identify differences between specified and actual behaviour. Verification and approval remain proportionate to risk and impact. Automated tests provide supporting evidence, not universal proof of correct behaviour or accessibility. See 8. Governance and Verification below. ### 4. One reference implementation. Multiple possible runtimes. React and Material UI provide the first working reference implementation of Shared Reality. The longer-term objective is to make relevant design and behavioural definitions sufficiently explicit that they can also guide implementations in Angular and legacy UI technologies. The implementation mechanisms may differ. The product UI semantics remain consistent and verifiable. Shared Product UI Definitions Semantics · States · Components · Experience - React / MUI Current reference implementation - Angular Future implementation target - Legacy UI Future implementation target One set of shared definitions guides every implementation. Only React / MUI exists today; Angular and legacy UI implementations do not exist yet. ### 5. Why Material UI? Material UI provides an established React component foundation with reusable APIs, documented interaction behaviour, theming capabilities and accessibility support. It also provides a substantial body of established UI conventions: component states, keyboard interactions, focus management, feedback mechanisms and common interaction patterns. Shared Reality builds on these existing conventions rather than redefining every standard UI behaviour in its own documentation. This allows the design system to concentrate on what requires explicit product-level decisions: shared semantics, purpose-defined components, cross-product Experience rules, consistent state representation, controlled variation and governance. MUI is also a practical reference for examining how interface states are calculated and rendered. Its palette mappings, state opacities, tonal variants and surface behaviour can be inspected, documented and compared with other implementations. But MUI is not the architectural source of truth. Shared Reality's explicit design definitions determine the result. React/MUI is one implementation of those definitions, not a mandatory technology choice for every adopting product. Where existing MUI conventions are sufficient, they can be inherited. Where shared product requirements go beyond MUI, the additional semantics, behaviours or constraints must be defined explicitly. This avoids duplicating an established component library while preserving control over product-specific decisions. ### 6. Structure: different responsibilities within one system The Explorer makes the different parts of Shared Reality visible. These sections have distinct responsibilities and are not interchangeable implementation layers (proposed in ADR 0005). | Area | Responsibility | | --- | --- | | Foundations | Visual and semantic primitives: tokens, colour, typography, spacing, elevation and brand assets | | Style Guide | Visual, layout, accessibility and component usage rules | | Experience | Interaction conventions, patterns and task-oriented experience guidance | | Components | Standard Material UI building blocks within the Shared Reality reference implementation, plus the adopted MUI X Date Picker | | TwistLock | The recognisable outer product chassis, including application bars, sidebar navigation and bottom bars | | Signature Components | Purpose-defined UIs implemented as individual reusable components | | Compositions | Purpose-defined UI/UX assembled from multiple components, including Configurable Modules | | Extended Components | Additional reusable components integrated into Shared Reality with documented provenance and behaviour | #### Controlled variation Not every domain-specific difference requires a separate component. A Configurable Module is a Composition with a stable structural foundation that adapts through explicit configuration, domain data and relevant states. The Patient Details Module demonstrates how a shared form structure can accommodate different field requirements and arrangements without an independent implementation for each variation. The module does not autonomously determine clinical requirements; those remain explicit product decisions. TwistLock addresses a different concern: a recognisable outer application structure that can accommodate different domains while maintaining shared product identity. Each section documents its own purpose and implementation. The Explorer's organisation supports discoverability without implying that all sections are the same kind of technical artefact. ### 7. Responsibilities and source of truth The approved, version-controlled definition in the repository is authoritative. Documentation and implementation follow it; a discrepancy is recorded and resolved through a reviewed change. | Responsibility | Holds | Where | | --- | --- | --- | | Definition | Approved meaning, rules, states and contracts | Design tokens (tokens/), state contracts (packages/contracts), Style Guide data, component metadata, architecture decisions (docs/decisions) | | Documentation | Explanation, examples and references | This Explorer, Storybook and package READMEs | | Implementation | Code that realises the definition | Component packages and the MUI theme (reference implementation) | | Runtime | Behaviour in a running product | Products that adopt Shared Reality | These responsibilities are related but not identical. Documentation makes a definition understandable. Implementation makes it executable. Runtime behaviour must be evaluated against the approved definition. Neither a rendered interface nor a generated implementation automatically becomes the authoritative specification. #### Governing principle ADR 0004 (docs/decisions/0004-governance-lifecycle-and-evidence.md), accepted 2026-10-23. Human-Approved Definition → Controlled Implementation → Verified Behavior → Human-Authorized Release → Traceable Product Use The sequence defines the responsibility boundaries; ADR 0004 sets the lifecycle and the evidence behind it. ### 8. Governance and verification ADR 0004, accepted 2026-10-23. Governance sits within Digital Product Design. Approval and verification are proportionate to risk and impact. Automated checks, AI-assisted development and AI agents can propose changes, identify inconsistencies and produce supporting evidence. They never replace human approval. #### Component lifecycle Set by Digital Product Design for each Shared Reality component and shown with it (Signature Components, Compositions, Extended Components) and in manifest/components.json. Since 2026-10-23 all are Candidate: specified and automatically tested, with the manual review pending; none is Stable yet. TwistLock reference examples have no status; MUI components retain their own upstream lifecycle. | Status | Meaning | | --- | --- | | Experimental | Being developed inside the system after adoption; not to be confused with an Exploration, which stays outside the system. | | Candidate | Sufficiently defined and undergoing verification. | | Stable | Verified and human-approved for release. | | Deprecated | Being phased out through controlled change. | #### Responsibility boundaries Shared Reality provides shared definitions, reusable implementations, documentation and verification support. Clinical safety, accessibility in each context of use and regulatory compliance are established by the adopting product. Product approvals, including usability engineering for regulated products, remain with the organisation that adopts Shared Reality. Relevant product-specific risk controls, validation activities and regulatory evidence must be established within that product's own lifecycle. Governance preserves the relationship between approved definitions, implementation, verification and accountable decisions. ### 9. AI governance: exploration, product and adoption Design tools and AI agents read the design system directly from its repository. AI governance defines what they may do in which situation, so that speed in exploration and reliability in products do not compete. Shared Reality does not have to grow with every new idea before anyone knows whether it works. Exploration is a regular innovation mode: teams and AI tools first develop the best experience for a task, and then decide what stays product-specific and what becomes part of the shared design system. - Exploration: free development of a solution with any UI and technical approach, starting from the brand and the tokens. - Product-specific solution: a solution built for one product that keeps the binding rules, without becoming part of the design system. - Adoption: the decision to make a solution part of the shared design system, so that every product can use it. | | Question | What applies | | --- | --- | --- | | Exploration | What may be used to find a solution? | Started by the word “Exploration” or “exploratory prototype”. The freedom covers UI and technical approaches: shadcn and other UI libraries, own components and icons, designer-supplied assets and detailed build instructions. The tokens are the starting point; deviations are possible. Data protection, fictional test data, semantics and the accessibility target stay. | | Product (default) | What may a product use? | Everything in the system, combined freely, and product-specific components that keep the binding rules: tokens, semantics, accessibility and usage rules. Own HTML and React are fine; what counts is respecting the rules, not the technology. Unapproved UI libraries and other design conventions are not. | | Adoption | What becomes part of the design system? | A solution to a problem that recurs across products, adopted deliberately: human approval, a recorded decision, origin and licence, a specification, tests, an accessibility check and the mapping to the tokens. | #### Example: a lab results table 1. Explore: “Exploration: develop the best experience for reviewing lab results.” The AI tool tries structures, status displays and cell interactions, with whatever components work best. 2. Decide, when it is useful: the result can be discarded; continued as a product-specific solution, rebuilt within the rules and without unapproved libraries; or proposed for adoption, if several applications share the problem. 3. Adopt, if proposed and approved: specification, tests, accessibility check and approval; from then on, every product may use it as a Signature Component, Extended Component or Composition. #### Brief for design tools A starting point that can be copied into a design tool connected to this repository. Exploration: Develop the best experience for this clinical task. Use the Shared Reality tokens as the starting point, respect semantics and accessibility, use fictional data only, and choose components and technical approaches freely. The solution does not need to become part of the design system yet. palette.ts (the PM-to-Dev Bridge) gives an Exploration the brand in minutes: the nine approved colour seeds, the smallest form of the brand. Product managers hand it, together with its resolved values, to exploratory tools and get a credible impression of their own brand. #### Exploration without drift - An Exploration never changes the sources of the system: tokens, components and rules stay as they are. - Everything that does not come from the system is listed with its origin and licence. - The marking is for the team: in the project and file names and in the code. Test participants see a product, not a label, so user tests stay realistic. - An Exploration reaches a product only as a product-specific solution rebuilt within the rules, or through adoption. #### How design tools work with it A design tool or AI agent connected to the repository reads AGENTS.md at its root: the rules for Exploration, products and adoption, and how to use palette.ts. The palette holds references; the values are the primitives in tokens/primitive/color.json, resolved per scheme in tokens/generated/values.json and shown on Foundations → Colors. #### Impact - Faster creation phase: ideas can be tried in hours, before the system has a component for them. - Product management takes part directly: with palette.ts, prototypes carry the brand without waiting for a design request. - No drift: exploration and the system are separated by rule; nothing passes from one to the other without a decision. - Realistic user tests: participants experience the prototype as a product. - AI under control: one rule set that every connected tool reads, with people deciding what becomes part of the system. - A focused system: the system grows through deliberate adoption, not with every new idea. Explore quickly with the brand. Build reliably with the system. ### 10. Product UI architecture within a broader idea Shared Reality's broader idea is a shared operational product reality that people, software services and AI agents can interpret. Interfaces are representations of that reality, not the reality itself. Design systems help stabilise shared meaning and behaviour across these different forms of participation. This page focuses on one part of that idea: Product UI Architecture. Shared tokens and component specifications do not by themselves establish a shared product reality. Product-specific domain semantics, workflows, risks and decisions are not defined by the UI component library. The design system therefore contributes to a broader product architecture without claiming to replace domain models, operational rules or regulatory processes. ### 11. What exists today — and what comes next #### Today Shared Reality currently provides a React/MUI reference implementation, DTCG-based design tokens, documented semantic colour mappings, selected visual state rules, reusable components, Signature Components, Experience guidance and automated checks. The Explorer makes these definitions and their relationship to the reference implementation visible. Additional implemented examples include the TwistLock design references, Extended Components and configurable Compositions such as Patient Details. AI governance is in place: products use the system, Explorations may use anything and are marked for the team, and only adopted elements become part of the system. Design tools and AI agents find these rules in AGENTS.md. The reference implementation runs on React and Material UI. Implementations for other frameworks build on the same definitions. #### Architectural direction The longer-term direction is a machine-readable Product UI Semantic Contract that can support different technical implementations and make their consistency easier to verify. Next steps: - More explicit behavioural contracts - Cross-framework reference implementations - Conformance checks - Additional state-dependent modules and Experience patterns - Governed AI-agent participation in product experiences ### The principle behind Shared Reality A product system can evolve through different technologies, devices and interfaces without requiring every implementation to be identical. What must remain coherent are the relationships between product meaning, states, specified behaviour, implementation and responsibility. System integrity emerges when those relationships are made explicit, maintained and verifiable. --- ## FAQ Short answers with a pointer to where each topic is defined. ### Using Shared Reality #### Can Shared Reality be used without React or MUI? Yes. Shared Reality provides shared design rules and semantic foundations: design tokens, colour role mappings, state values, component specifications, Style Guide rules and interaction patterns. React with Material UI is the current reference implementation. Other frameworks, including Angular, can implement the same relevant definitions, although framework-specific implementation details may differ. A separate Angular or legacy implementation is not currently provided. The Idea → Shared rules. Different implementations. Foundations → Colors #### What does another implementation need to reproduce? Values and rules marked as Shared Reality definitions, together with inherited MUI values that affect the specified visual or behavioural result. These may include state opacities, disabled colours, tonal variants and dark-mode elevation overlays, where relevant and documented with resolved values. Implementation details, such as how MUI draws a state layer, produces a ripple effect or structures its styling engine, do not necessarily need to be copied. The specified semantics and behaviour must remain consistent and verifiable. The Idea → Three levels: semantics, UI architecture and behavioral experience Foundations → Shadows #### Where are the authoritative definitions? In the repository: design tokens, state contracts, Style Guide data, component metadata and architecture decisions. The Explorer and Storybook document and demonstrate those definitions. The approved, version-controlled definition is authoritative; a discrepancy between definition, documentation and implementation requires reviewed resolution. The Idea → Responsibilities and source of truth ### Components #### What is the difference between a Signature Component and a Composition? A Signature Component is a purpose-defined UI implemented as a single reusable component. A Composition is a purpose-defined UI/UX assembled from multiple components. Both follow the relevant shared governance and lifecycle principles. A Configurable Module is a Composition that adapts to explicit, governed configuration. Patient Details is an example. Compositions → Overview #### What happens when a product needs a change to a shared component? The change is assessed first: does it belong in the shared library, or should it remain a product-specific adaptation? Shared changes require coordinated definition, implementation and verification. The decision depends on the scope, reuse, compatibility and impact of the change. #### What do the lifecycle statuses mean? Experimental: being developed inside the system after adoption (not the same as an Exploration, which stays outside the system). Candidate: sufficiently defined and undergoing verification. Stable: verified and human-approved for release. Deprecated: being phased out through controlled change. Digital Product Design sets the status of each component (ADR 0004). Since 2026-10-23 the Signature Components, Compositions and the Data Table are Candidate; none is Stable until its manual review is recorded. MUI components retain their own upstream lifecycle. The Idea → Governance and verification ### Quality and regulation #### Do the automated checks prove accessibility? No. WCAG 2.2 AA is the target. Automated checks, including axe-core, support the review. Browser, keyboard and screen-reader review remains necessary and must be recorded with the version to which it applies. Accessibility must also be evaluated within the adopting product’s actual context of use. Style Guide → Accessibility #### Are the healthcare examples real? No. All patients, staff, records and organisations in the examples are fictional, and the demonstrations send and store nothing. A product that adopts Shared Reality remains responsible for its own approvals, including applicable usability engineering, risk management and regulatory requirements. #### Can design tools and AI agents use other UI libraries? In an Exploration, yes: when the brief says “Exploration” or “exploratory prototype”, design tools and AI agents may choose any UI and technical approach, including shadcn and other UI libraries, with the tokens as the starting point. Products use the system and may build product-specific solutions that keep its rules; another library reaches products only through adoption into the design system. The Idea → AI governance #### How does something become part of the design system? Through adoption: human approval, a recorded decision, origin and licence, a specification, tests, an accessibility check and the mapping to the tokens. It then becomes a Signature Component, an Extended Component or a Composition, and every product may use it. AI agents may prepare an adoption; they never approve it. The Idea → AI governance #### Who approves changes? Governance sits within Digital Product Design, proportionate to risk and impact (ADR 0004). Automated tooling and AI agents can prepare changes and supporting evidence, but never approve them. Product-specific release, validation and regulatory approvals remain with the responsible adopting organisation. The Idea → Governance and verification --- ## Storybook The workshop of Shared Reality: every component on its own, with its states, its options and automated accessibility checks. ### What Storybook is for This Explorer explains the decisions, rules and purpose behind Shared Reality. Storybook shows the implementation: each component and each Explorer page as an isolated story. Designers and developers can switch between light and dark mode and the three contrast levels in the toolbar, try the options of a component, and see the automated accessibility checks of every story. Storybook uses the same theme, tokens and font as this Explorer, so a component looks and behaves the same in both. Open Storybook ↗ --- ## Foundations Colour, typography, spacing, corner radius, shadows, icons and brand as design tokens: one definition that every implementation reads, instead of values copied into each product or framework. ### Impact - One value source: every colour exists once, as a primitive. Roles and component deviations only reference it, so products and frameworks cannot drift apart. - Traceable decisions: every deviation from the colour step rule and every approved contrast deviation carries its date, basis and reason in the token file. - Framework-independent: MUI is the first implementation, not the source. Other frameworks and AI agents read the same token files. - Verifiable: a framework-free check measures contrast by use; separate adapter checks prove that the MUI implementation follows the tokens. ### Key decisions - Three token layers (ADR 0009): primitives hold the values, semantic tokens define the roles of all six colour schemes, component recipes only the deviations of single components. - Six explicit colour schemes: light and dark, each in standard, medium and high contrast; every role is listed per scheme, nothing is inherited or calculated in code. - Contrast by use (WCAG 2.2): text 4.5:1, large text and graphics 3:1. Four deviations are approved after visual review and documented as not conformant, never as a general approval. - No colour model in the system: values are chosen on the existing scales and reviewed visually; a colour model may only propose a value, which needs approval. - Two kinds of verification: architecture checks define Shared Reality; adapter checks are bound to one framework version, so an upgrade never redefines the system. - One generated, library-neutral CSS file makes every token usable outside MUI (ADR 0010); MUI styles MUI components only. - Foundations equal the MUI defaults wherever possible (spacing, shadows, breakpoints, motion) and are not applied twice; Open Sans is self-hosted. ### Read more Colors: the six schemes, their contrast and every deviation with its reason All Tokens: the three token layers, searchable Decision records: docs/decisions/0008-colour-reset.md and 0009-semantic-and-component-colour-tokens.md --- ## Experience How people interact with and move through a product, from the behaviour of a single field to journeys across products and devices. Each level is documented where it belongs. ### Levels of Experience Not every level of interaction is a pattern. | Level | Scope | Example | Documented in | | --- | --- | --- | --- | | Component behaviour | Local interactions and states of one component | A select opens with Enter and is navigated with the arrow keys; an invalid field shows its error text. | The component page (Components, Signature Components) | | Interaction pattern | A reusable solution across components | Edit and Save, Search and Select, Login, Password Reset, Error Recovery | Experience → Interaction Patterns | | Task flow | Connected steps for one task | Registering a new patient: search for an existing record, enter details, confirm. | With the product (future reference examples) | | User journey | Several tasks, contexts, products or devices | Booking an appointment on a phone, checking in at the practice, reading a summary in a portal. | With the product (future reference examples) | A Login pattern is not the same as a complete cross-device patient journey: the pattern solves one recurring interaction, the journey connects many of them across contexts. Component Behaviour Local interactions and states of an individual component, documented with that component. Example: A field gains focus, a list opens with the arrow keys, an invalid field shows its error. Interaction Pattern A reusable interaction solution across components. Example: Edit and Save, Search and Select, Login, Password Reset, Error Recovery Task Flow Connected steps for completing one specific task. Example: Registering a new patient: search for an existing record, enter details, confirm. User Journey A broader experience spanning multiple tasks, contexts, products or devices. Example: A patient books an appointment on a phone, checks in at the practice and later reads a summary in a portal. ### How Compositions fit in Compositions take part in patterns and flows without owning them. - Component behaviour inside a Composition stays the components' own behaviour. - A future Edit and Save interaction pattern can coordinate the Patient Details Module: switch between view and edit mode, request validation, save, cancel, move focus to the first error and report the result. - Task flows and journeys combine several Compositions and patterns; they belong to the product. Compositions → Patient Details ### User and access context Experience depends on who is acting, in which role, and with which permissions. User & Access Context Who is using the product (user model), their identity and permissions, and the information architecture they move through. The authenticated user is not necessarily the patient whose data is shown. A UI may reflect permissions; hidden or disabled controls are not authorization. - User model: the roles and situations of the people using the product, for example clinical staff, administration or patients. - Identity and permissions: who is authenticated and what they may see or do; enforced by the product and its services. - Information architecture: how content and functions are organised and found. ### Current scope Interaction Patterns lists the current patterns. Sign in with Password Reset and Switch user exist as interactive demonstrations in TwistLock → Sign in and TwistLock → Switch user: complete step sequences with synthetic data and a simulated sign-in. They are not documented as Interaction Patterns yet; Edit and Save, task flows and user journeys are not implemented as reference examples. Experience → Interaction Patterns --- ## Components The standard MUI components with the Shared Reality theme, documented with their real capabilities, states and accessibility notes, grouped as in the MUI documentation. ### Impact - Nothing rebuilt: standard components keep their behaviour, keyboard handling and accessibility semantics; Shared Reality provides the theme, not new components. - Consistent colour everywhere: every component takes its colours from the semantic roles of the active scheme, in light and dark mode and all contrast levels. - Few, documented deviations: three groups of style overrides exist (warning text, tooltip, chat: timestamps and composer border), each a component recipe with its reason; everything else is the component’s own styling. - Honest documentation: each value is marked as a Shared Reality rule, an inherited MUI default or an implementation detail, so other frameworks know what to reproduce. ### Key decisions - MUI 9.5.0 is the reference implementation; the installed type definitions are the technical reference, no props are invented. - Warning text uses the darker warning role in light mode, because the warning colour is below 4.5:1 as text on white; fills and borders keep the warning colour (component recipe warningText). - Tooltips use an inverse surface — dark in light mode, light in dark mode — instead of a grey that hardly stands out in dark mode (component recipe tooltip). - Tertiary is available as a colour on every component that accepts palette colours, through MUI’s documented colour extension. - Dates use the adopted MUI X Date Picker (community package, German locale) instead of custom calendars or native date inputs. - Automated checks support the accessibility review; browser, keyboard and screen-reader review remain necessary. ### Read more Button: variants, colours, states and accessibility Colors: component recipes and approved contrast deviations Decision records: docs/decisions/0008-colour-reset.md and 0009-semantic-and-component-colour-tokens.md --- ## TwistLock People should not have to relearn a product every time they change it. TwistLock keeps the shared conventions recognisable across domains: where people find navigation and identity, how they orient themselves, and how sign-in, user switch and top-level actions behave. Domains, content and their workflows can differ. ### What TwistLock is TwistLock defines how the outer product frame stays recognisable across domains: how application regions relate to each other and how shared product identity connects with domain-specific experiences. It is not simply a collection of navigation components. - Product identity and recognisability - Navigation and orientation across domains - Consistent structural relationships between application regions - Shared layout and interaction conventions - Continuity across different product contexts ### Shared chassis and domain responsibilities TwistLock may render explicitly supplied domain configuration. It never infers domain requirements, permissions or clinical meaning. #### TwistLock (shared chassis) - Persistent product identity - Structural navigation conventions - Relationships between application regions - Shared visual and interaction consistency - Responsive adaptation - Accessibility conventions - Recognisable cross-domain product framing #### Consuming product or domain - Navigation destinations - Domain labels and information architecture - Contextual actions - Search scope and result behaviour - User permissions and authorization - Domain-specific states and workflow requirements ### The Explorer's own frame The Explorer's App Bar and navigation are implemented once (ShellAppBar and ShellNavigation) and serve both the shell of this documentation application and the TwistLock design references, which supply synthetic healthcare data. --- ## Signature Components Signature Components are purpose-defined user interfaces implemented as individual reusable components. They show people which level of interaction they are on. Each Signature Component follows the relevant Shared Reality semantic foundations, interaction conventions and governance principles. ### Purpose A Signature Button, Chip, Select or Icon Button marks a top-level interaction, such as the main action of a screen or its central filter. Standard components handle the subordinate, ordinary interactions. Across products this creates a hierarchy people can learn: which role an interaction plays in the overall hierarchy. The meaning comes from consistent use, placement, behaviour and visual distinction, defined in the usage rules: not every top-level control has a Signature equivalent, and standard components are not replaced wholesale. That the current implementations build directly on MUI is a technical advantage: native behaviour and accessibility are kept, and the Signature layer is defined once. Style Guide → Component Usage ### Shared foundations Signature Components use the Shared Reality design tokens and the palette of the active MUI theme: they inherit its surfaces and colours in all six colour schemes and define no colours of their own. The current implementations are built on standard MUI components and keep their native sizing, keyboard interaction and accessibility conventions. What they add is documented once: the shared Signature contract (surface, foreground, hover, focus ring, disabled state and motion) and a framework-neutral specification per component (purpose, dimensions, shape, states and accessibility), so that other implementations can reproduce the documented behaviour. Foundations → Colors Style Guide → Component Usage (Signature contract) ### Available components Generated from the Explorer page registry; purpose and basis from the component specifications. | Component | Purpose | Built on (reference implementation) | Status | | --- | --- | --- | --- | | Content Box | Carrier of a page’s content: one box per topic, on the page background. Content Boxes never nest. | Paper | Candidate | | Icon Button | Top-level icon action of a screen or the application shell (e.g. the Explorer settings). | IconButton | Candidate | | Chip | Primary filter or selection at the top of a screen. | Chip | Candidate | | Selectable Chip | Primary filter or selection at the top of a screen, with an on/off state. | Chip (via SignatureChip) | Candidate | | Appointment Time Chip | The central time selection of a scheduling screen (no booking logic). | Chip (via SignatureSelectableChip) | Candidate | | Button | The main action at the top of a screen’s hierarchy. | Button (text variant) | Candidate | | Select | The primary top-level filter or selection input. | Select, InputBase, FormControl; the list is a standard MUI Menu | Candidate | | Autocomplete | The primary top-level filter or selection input for long or searchable lists. | Autocomplete, TextField; the list is the standard MUI popup | Candidate | | Dropdown | A top-level action that opens a standard MUI menu. | SignatureButton trigger, Menu, MenuItem | Candidate | ### Lifecycle and responsibility Signature Components belong to the shared component library and follow its governance: changes are proposed, verified and approved by people, and automated checks support but never replace that review. Their lifecycle status is set by Digital Product Design (ADR 0004): all are Candidate since 2026-10-23, specified and automatically tested, with the manual review pending. The Idea → Governance and verification --- ## Compositions Components provide reusable interface elements. Compositions bring them together into meaningful, configurable product experiences. ### From reusable components to coherent product experiences A Composition defines how interface elements, information and interaction patterns work together for a particular purpose — without taking ownership of the underlying business logic. Products supply the data, configuration and operational state. Compositions determine how these inputs are structured, presented and made understandable to people. ### Architectural decisions - Separate experience from operational authority. A Composition can represent a product state without owning or changing its meaning. Business rules, permissions, decisions and state transitions remain with the responsible product and runtime services. - Reuse patterns without prescribing product behaviour. Compositions establish consistent experience structures while allowing products to supply domain-specific content, configuration and actions. - Make system behaviour understandable. Information, status and responsibilities should be represented consistently and accessibly, including when interactions involve AI agents. ### Architectural impact - Consistency: Shared experience patterns across products and contexts. - Scalability: Reusable structures reduce repeated design and implementation decisions. - Governance: Operational authority remains with the systems responsible for it. - Traceability: Representations can remain connected to their underlying product states and contracts. - Adaptability: Experiences can evolve without duplicating domain logic inside the interface. ### Composition and Configurable Module Composition = purpose-defined structure and behaviour. Configurable Module = Composition + governed configuration and controlled adaptation. Every Configurable Module is a Composition. Not every Composition is a Configurable Module. | | Composition | Configurable Module | | --- | --- | --- | | Structure | Defined by the Composition | Defined by the Module; stable across products | | Configuration | Not required | Explicit, typed and limited: e.g. required fields, option lists, read-only fields, controlled extensions | | Domain dependence | None or fixed | Supplied by the consuming product; never discovered by the Module | | Example | A fixed arrangement of components with one purpose | Patient Details | ### What influences a Configurable Module A Module receives everything it adapts to from its consuming product context. It does not discover clinical requirements, and it does not grant access rights. - Domain configuration Which fields, options, requirements and extensions are relevant in this product context. Supplied by: Consuming product - Data The values to show or edit, and which data is unavailable. Supplied by: Consuming product (from its domain services) - Operational state The state of the domain entity or process, e.g. an active or inactive patient record. Supplied by: Domain system - Module UI state Editable, read-only (view mode) or loading. Supplied by: Consuming product Configurable Module Stable structure and behaviour; presentation adapted within the supported configuration. Inputs come from the product and domain; the Module only represents them. #### Configuration Determines which fields, options, requirements and extensions are relevant for a particular product context. Configuration is limited to what the Module supports and never replaces its base structure. Not every backend field becomes a UI field: the product decides what is relevant. #### State-dependent behaviour Determines how the Module represents and responds to supplied operational states. The meaning of a state and the authority to change it remain with the product and domain system. ### States Four kinds of state, often confused. Only the first two belong to the UI. | Kind | Example | Owned by | | --- | --- | --- | | Component state | A field is focused or invalid. | The component (MUI behaviour) | | Module state | The whole form is loading or read-only. | The Module, set by the consuming product | | Operational state | A patient record is active or inactive; an encounter is open or closed. | The product and domain system | | State transition | An authorized action changes an operational state, e.g. closing an encounter. | The product and domain system; the UI offers the action | Operational State A meaningful state of a domain entity or process. It may influence the information and actions a Module presents, but its meaning and authority belong to the product or domain system. Distinct from UI states such as focused, disabled, loading or error. Example: A patient record is active or inactive; an encounter is open or closed. ### Relationship to Components and Experience - Compositions are built from Components and keep their specifications, the semantic tokens and the accessibility requirements. - Component behaviour, such as focus or list navigation, stays with the components and is not redefined by the Composition. - Interaction patterns coordinate Compositions within larger tasks. A future Edit and Save pattern, for example, can switch Patient Details between view and edit mode, request validation and save. See Experience → Overview. ### Responsibilities outside the design system - Domain data models, clinical terminology and clinical or business requirements. - Operational states, their meaning and their transitions. - Persistence, integration with backend services and authentication. - Authorization: the authenticated user is not necessarily the patient whose data is shown, and hidden or read-only fields are not access control. - Product approvals, including usability engineering for a regulated product. Domain Configuration Explicit product or domain decisions about relevant fields, labels, options, visibility, required status, validation rules and permitted extensions. Example: A product requires the postal code and supplies its own option list for gender. User & Access Context Who is using the product (user model), their identity and permissions, and the information architecture they move through. The authenticated user is not necessarily the patient whose data is shown. A UI may reflect permissions; hidden or disabled controls are not authorization. ### Examples The implemented Compositions are listed in the navigation under Compositions. A Patient Header is planned as an example of state-dependent behaviour: how a Module presents supplied operational states, such as an active or inactive patient record, without taking over domain authority. --- ## Extended Components Additional UI components integrated into Shared Reality. ### Why shadcn is an additional source shadcn/ui provides components and interaction patterns that are missing from, or insufficiently supported by, MUI Core. Its components are source code copied into a project rather than an npm library, so they are kept in their own package (@shared-reality/shadcn-components) with a provenance record for every component, instead of being rebuilt with MUI or mixed into the MUI Core and Signature Components. New shadcn components reach products only through adoption into the design system, with a provenance record (ADR 0001). In an Exploration they may be used freely. | Source | Status | Role | | --- | --- | --- | | MUI Core | approved | Primary component foundation | | Signature Components | approved | Governed adaptations and compositions of MUI Core components, assigned by information hierarchy | | shadcn/ui | approved | Additional source for components and interaction patterns missing from or insufficiently supported by MUI Core, kept as a distinct, traceable family | | MUI X | under-evaluation | Candidate for advanced data components (e.g. Data Grid Community) | | TanStack (Table, Virtual) | under-evaluation | Candidate headless behaviour engines with MUI presentation | Decision record: docs/decisions/0001-shadcn-ui-as-additional-component-source.md ### Tokens as the only source Extended Components follow the same Shared Reality tokens as every other component, in all six colour schemes. They read them from one generated CSS file that any library or framework can use, so components from different sources can share a page while every value stays traceable and verified. | Intent | Decision | | --- | --- | | The same look and meaning in every component family | The tokens are the only source. MUI styles MUI components only; Extended Components never read the MUI theme. Component recipes describe a kind of component, not a library, and apply to every family. | | Usable with any library or framework | One library-neutral CSS file is generated from the tokens: foundations (typography, spacing, radius, shadow, motion, z-index, opacity) and the colours of each scheme as --sr- custom properties. It is never edited by hand. | | Components from different sources on one page | Shared Reality defines the contract: the data-sr-scheme attribute, the scheme names and the --sr- names. Every rendered part, including menus and dialogs, lies inside a scheme; each application decides where the attribute sits (this Explorer: the document root). | | Every value traceable | The shadcn mapping only translates each shadcn variable to a token. What a component needs and the tokens do not yet hold becomes a recorded token decision, never a framework default. | | Readable in every scheme | Text on filled colours and on hovered or selected surfaces is defined by tokens and checked by use (text 4.5:1); the calculated results of interaction states are verified, not only their source. | | Changes under control | Decisions are the source; calculated values are generated output. A change shows every affected value per scheme in the diff of the generated values, and a person approves it. | Decision record: docs/decisions/0010-token-runtime-for-extended-components.md ### Integration into Shared Reality shadcn's Tailwind theme and CSS variables are not installed. Components read existing tokens through an explicit mapping (packages/component-sources/mappings/shadcn-theme.mapping.json). #### Colours Values of the active scheme (light), traceable from the shadcn variable to its semantic role (tokens/semantic/color.json), its primitive and the custom property in the generated token CSS. Light/Dark and contrast follow the Explorer settings; shadcn's .dark class is not used. | shadcn variable | Semantic role | Token CSS | Primitive | Value | | --- | --- | --- | --- | --- | | --background | background.default | --sr-background-default | {color.secondary.50} | #F4F6F7 | | --foreground | text.primary | --sr-text-primary | {color.text.primary} | #101A1D | | --card | background.paper | --sr-background-paper | {color.white} | #FFFFFF | | --card-foreground | text.primary | --sr-text-primary | {color.text.primary} | #101A1D | | --popover | background.paper | --sr-background-paper | {color.white} | #FFFFFF | | --popover-foreground | text.primary | --sr-text-primary | {color.text.primary} | #101A1D | | --primary | primary.main | --sr-primary-main | {color.primary.500} | #176B87 | | --primary-foreground | primary.contrastText | --sr-primary-contrast-text | {color.white} Rule of ADR 0010: the first of white, color.text.primary and black that reaches 4.5:1. | #FFFFFF | | --secondary | secondary.main | --sr-secondary-main | {color.secondary.500} Decision 2026-10-19: shadcn secondary is the Shared Reality secondary colour (slate), so "secondary" means the same in every component family; subtle grey fills use muted. | #485963 | | --secondary-foreground | secondary.contrastText | --sr-secondary-contrast-text | {color.white} Rule of ADR 0010: the first of white, color.text.primary and black that reaches 4.5:1. | #FFFFFF | | --muted | surface.muted | --sr-surface-muted | {color.neutral.200} Subtle opaque neutral surface (decision 2026-10-19, ADR 0010: neutral .200 light, .900 dark). | #D7D9DA | | --muted-foreground | text.secondary | --sr-text-secondary | {color.text.secondary} | #25363A | | --accent | surface.muted | --sr-surface-muted | {color.neutral.200} Highlight surface in menus and lists (decision 2026-10-19, ADR 0010: neutral .200 light, .900 dark). | #D7D9DA | | --accent-foreground | text.primary | --sr-text-primary | {color.text.primary} | #101A1D | | --destructive | error.main | --sr-error-main | {color.error.700} | #D32F2F | | --destructive-foreground | error.contrastText | --sr-error-contrast-text | {color.white} Rule of ADR 0010: the first of white, color.text.primary and black that reaches 4.5:1. | #FFFFFF | | --border | divider | --sr-divider | {color.secondary.200} | #CBD3D7 | | --input | text.secondary | --sr-text-secondary | {color.text.secondary} Border of input fields (decision 2026-10-19, ADR 0010); at least 3:1 against the surface. | #25363A | | --ring | primary.main | --sr-primary-main | {color.primary.500} Focus indicator colour, as in MUI. | #176B87 | Not mapped: chart-1 … chart-5, sidebar-*. #### Typography, spacing and radius - Font family: font.family.base. From the generated token CSS (--sr-font-family-base and --sr-typography-*); no font is loaded by components. - Sizes: text-xs → typography.caption, text-sm → typography.body2, text-base → typography.body1, text-lg → typography.subtitle1. - Weights: font-normal → font.weight.regular, font-medium → font.weight.medium, font-semibold → font.weight.medium, font-bold → font.weight.bold. - Tailwind spacing step n equals n × 4px. Values on the 8px scale map to spacing tokens (step 2 → spacing.1, step 4 → spacing.2, …). Step 0.5 (2px) maps to spacing.quarter (decision 2026-10-19, ADR 0010). Other off-scale values (1, 1.5, 2.5, 3, …) are allowed only as recorded local modifications for intrinsic component geometry. - radius, radius-sm, radius-md, radius-lg and radius-xl all map to radius.base (the only radius token). rounded-full stays for shapes that are intrinsically circular or pill-shaped, as MUI does for Chip, Avatar and Switch. #### States, behaviour and accessibility - hover: Neutral hover: --sr-state-hover (semantic pair state.hover: text colour at the hover opacity, ADR 0010). Hover of filled colours (bg-primary/90): the dark role of the colour (e.g. primary.dark).. - focus-visible: Visible outline in the ring role (primary) with at least 3:1 against the adjacent colours; the reduced-opacity ring is not adopted without a contrast check. - disabled: Element opacity opacity.disabled (0.38) instead of shadcn's 0.5, recorded as a local modification (ADR 0010).. - invalid: error role, driven by aria-invalid as upstream. - open / checked / selected: Preserved: data attributes set by the Radix or Base UI primitive; only their styling is mapped Selected rows: --sr-state-selected (semantic pair state.selected).. - Behaviour, focus management and keyboard handling come from the upstream primitive (Radix UI or Base UI) and are preserved. Any change to behaviour is a recorded local modification. - Each component declares its WAI-ARIA Authoring Practices pattern and keyboard map in its provenance record. - Keyboard, screen reader, focus visibility, target size (WCAG 2.5.8) and contrast in all six schemes are verified separately; rendering successfully is not evidence. - Upstream accessibility behaviour is preserved; regressions introduced by adaptation block approval. #### Styling approach (approved) Adapted source: upstream component structure, props, variant names, primitives and data attributes are kept; Tailwind class strings, cn() and class-variance-authority are replaced by Emotion styles that read the generated Shared Reality token CSS (tokens/generated/tokens.css, --sr- custom properties; ADR 0010). Nothing is read from the MUI theme; MUI controls used inside a component stay MUI. - Rejected: Install Tailwind and map its theme to MUI. Introduces a second styling system (utilities and preflight next to CssBaseline) and duplicate CSS variables. - Rejected: Copy shadcn CSS variables into a stylesheet. Creates a competing token authority. ### Provenance and SBOM traceability The lockfile only knows npm packages. Copied and adapted source is traced by provenance records in packages/component-sources/registry. | Kind of code | Recorded in | | --- | --- | | Third-party npm dependencies | package.json, pnpm-lock.yaml and the record (exact version, licence) | | Copied or adapted shadcn source | Provenance record: upstream commit, source URL, licence, file hashes, local modifications; SPDX headers in each file | | Original Shared Reality code | originalCode in the registry, or origin "original" in a record | #### Validation - Every file in the package needs a provenance record or must be listed as original code. - Copied and adapted files need SPDX headers; a changed file whose hash is not updated in the record fails. - Upstream revisions are full commit SHAs; npm dependencies are recorded with exact versions. - A component is verified only when behaviour, keyboard, screen reader, focus visibility, contrast in all six schemes, target size and theme integration have passed with evidence. Rendering successfully is not a check. #### SBOM - CycloneDX 1.6 (primary): vendored components with pedigree (upstream ancestor, commits, patches, notes) and file hashes, merged with the npm dependency SBOM. - SPDX 2.3 (secondary): packages and files with checksums, licence and copyright text, modification relationships. - SBOMs are generated from the provenance records and the lockfile, never maintained by hand. No generator is installed yet. ### Approved components No shadcn component is approved yet: imported components stay pending until every verification check has passed with evidence. ### Pending verification - Table: unverified Integration exceptions awaiting approval before the first component (4): - No 600 font weight token - Off-scale spacing in component geometry - lucide-react icons - Radix UI or Base UI primitives as npm dependencies