Design and ownership

11. Atomic design as a practical composition model

11.1 Reuse begins with recognizable responsibilities

Atomic design provides a vocabulary for moving from small units to complete interfaces: atoms, molecules, organisms, templates and pages. The methodology describes these levels as a way to reason about parts and wholes, not as a rigid sequence that replaces design judgment. 11

In Surface, an atom can be a text element, icon, button or editable field. A molecule combines a few units into one recognizable control, such as a labelled field. An organism represents a substantial interface region, such as a message composer or participant picker. A template describes an arrangement of regions. A page binds that arrangement to an actual product workflow.

Figure 15. A conversation page combines a layout template with product organisms. The composer and timeline reuse smaller controls, but remain understandable product concepts rather than arbitrary wrappers. See the illustrated PDF for the diagram.

The labels do not determine implementation complexity. A button atom can have a sophisticated behavior contract. A large organism can be stateless and easy to test. Neither automatically requires its own graph node or deployment boundary.

11.2 Product meaning belongs at the appropriate level

The framework can define a generic chip. BestBuds can define a campaign-stage indicator using that chip and its product semantics. The framework does not need to know what a campaign stage means to provide good typography, selection behavior or focus treatment.

A product organism receives a presentation model and emits typed events. It should not locate repositories from ambient globals. That keeps it usable in previews, tests and generated compositions with controlled data.

For example, an event card can receive its title, image, availability description and action bindings. A page or feature owner decides where those values come from. The card can therefore be rendered in a feed, a conversation or a preview without bringing an entire application service graph into its implementation.

11.3 Slots express composition intent

A slot is a named place where content can be supplied. It is more informative than a generic child array when the component expects different kinds of content in different positions.

Figure 16. An event card separates its leading media, descriptive content and actions. Slot contracts keep those roles meaningful for manual and generated composition. See the illustrated PDF for the diagram.

A label slot can permit inline text and a decorative icon. An action slot can permit a bounded set of controls. A supporting-pane slot can accept a product organism. These categories prevent an agent from inserting an unrelated navigator into a place intended for a short label.

Local code can expose richer composition when useful. The contract must simply identify which forms remain portable and which rely on a renderer-specific extension. Flexibility is not the same as pretending every arbitrary child is valid everywhere.

11.4 Compound controls need explicit shared state

Tabs are a useful example. The selected tab, the tab list and the displayed panel are related. Their relationship should be defined by a parent contract or explicit model, not by incidental position in a child list.

If an agent inserts a tab, the selected identity must still refer to the intended tab. Stable keys are preferable to an index whose meaning changes when siblings are added. The same principle applies to menu items, reorderable lists and repeated form rows.

Controlled and locally managed variants also need a clear distinction. A field that receives an authoritative value cannot silently treat an unrelated default as a second source. The API states whether the owner controls the value or the component owns a local editing session that reports changes.

11.5 Avoid abstractions that hide the page

A screen should remain readable as a composition of meaningful regions. Extracting every pair of layout calls into a one-use wrapper can make the page harder to understand. The right question is whether the extracted name expresses a reusable concept or independently testable behavior.

A MessageComposer is useful because it names a coherent interaction region. A wrapper named BottomRowContainer2 often reveals only that code was moved. Atomic design should improve the architecture's vocabulary, not reward the number of component files.

The same standard applies to graph decomposition. A feature boundary is useful when it owns a lifecycle, contract or updateable region. A spacer does not need an actor because it appears in a visual hierarchy. Sharing one graph foundation does not require uniform runtime machinery for every atomic level.

11.6 The catalogue becomes more useful to agents at higher levels

An agent asked to build an event-planning interface has less room for error when it can compose an approved participant picker, schedule summary and confirmation region. Reconstructing those experiences from hundreds of anonymous boxes gives the model more freedom but fewer guarantees.

Higher-level organisms do not eliminate customization. Their slots and properties expose the variation the product permits. When a new kind of organism is needed, it can be developed, tested and registered through the same process as human-authored components.

Atomic design consequently supports both development productivity and bounded runtime composition. The important asset is not a library of attractive shapes. It is a hierarchy of meaningful, tested units whose contracts remain usable across renderers and authors.

12. Themes, tokens and interchangeable visual languages

HLD — Arrows follow theme resolution and target lowering. Typed recipe output replaces a second product stylesheet. Open the diagram for full size.

12.1 A palette is only one part of a theme

A palette assigns colors. A visual language describes more: how surfaces are separated, how controls receive emphasis, how corners and borders are used, how typography establishes hierarchy, and how interaction changes appearance.

Two themes can use the same colors and still feel different. One may be flat and editorial. Another may use a fixed contact plate, a moving face and a hard outline. A glass-like language may rely on translucency, while an accessible high-contrast profile may deliberately remove it.

Surface therefore separates four dimensions. Brand supplies product identity. Design language supplies visual grammar and response. Mode selects a supported light, dark or other appearance. Density adjusts the spacing and sizing appropriate to the interaction context. User preferences and renderer capabilities constrain the resulting combination.

These dimensions are not a promise that every possible combination is valid. A package declares the combinations it supports. Unsupported combinations produce a deliberate fallback or validation result rather than a partially themed interface.

12.2 Reference tokens, semantic roles and recipes

A reference token names a raw design value, such as a palette color or spacing step. A semantic role names its purpose, such as content.primary or action.destructive.background. A component recipe explains how a component uses those roles.

Consider the label on a strong button. The product screen requests a strong action. The recipe selects the strong-action background and its corresponding content role. The brand and mode resolve those roles to concrete values. The screen does not need to know which palette entry provides sufficient contrast on that background.

Figure 17. The token pipeline preserves the difference between a raw value, a semantic purpose and a component-specific use. Theme selection and user constraints resolve these into one coherent snapshot. See the illustrated PDF for the diagram.

This chain is valuable for debugging. An inspector should be able to explain that a border came from the selected field recipe, which referenced an invalid-state role, which resolved through the current brand mode. Showing only the final color loses the reason behind it.

DTCG's typed token format provides an interchange vocabulary for tokens, aliases and composite values. Surface can use that format with explicit extensions rather than inventing an incompatible token island. The interchange representation is distinct from the compact values consumed during rendering. 12

12.3 A resolved theme is a coherent snapshot

The theme resolver checks definitions, aliases, resources and supported combinations before publication. It then produces one immutable snapshot for a scope. A snapshot has an identity and revision, so caches and inspectors can identify the decision set that produced a component's appearance.

The conceptual snapshot contains colors, typography and resource references, spacing, shape, depth and motion decisions. Generated accessors keep ordinary component code typed; a generic token map is an interchange or diagnostic representation, not an invitation to scatter string lookups throughout the application.

Coherent publication prevents mixed states. A consumer must not read the new background with an old foreground role because the package updated them separately. Preparing required fonts or a declared fallback before activation also reduces avoidable visual discontinuity.

12.4 Material is an adapter, not the universal model

Material provides a useful implementation foundation for many controls. A Surface Material adapter maps neutral roles into the values required by the chosen Material implementation. It includes typography and shapes as well as colors.

The mapping must be complete for the supported controls. A dark appearance can still inherit inappropriate defaults if only some roles are supplied. An adapter test should therefore check the actual role set used by components, rather than assuming that a function named “dark theme” guarantees every downstream value.

The shared model must also permit treatments that Material does not directly represent. A hard contact shadow, asymmetric product corner or field-reactive surface can be expressed through additional recipe concepts. These are not reasons to put all Material classes into every shared component contract.

Compose's custom-design-system guidance supports replacing or extending theme systems rather than treating one supplied theme as the only possible design architecture. 13

12.5 Six languages, one semantic action

Figure 18. Illustrative treatments for the same action. The visual language changes borders, depth, shape and typography, while the action and its accessibility obligations remain stable. See the illustrated PDF for the diagram.

In a Material-like language, strong emphasis can be expressed with a filled control and familiar tonal relationships. In NeoBrutalism, the same emphasis may use a thick outline and an offset contact plate. Glass can use layered translucency when the renderer and contrast policy permit it. NeoMorphism can use opposing light and shadow, but needs explicit boundaries and focus indicators where subtle depth is insufficient.

NeoRetro can use deliberately angular geometry and distinctive typography. Cell-shaded treatment can use stepped tones and graphic outlines. These names describe families of recipes, not exact renderer-independent pixel formulas.

A theme implementation cannot use a visual convention to change application availability. A destructive action still needs destructive semantics. A selected item remains selected even when its outline becomes a fill. The shared behavior and semantic contract remain underneath the visual experiment.

12.6 Data-only theme switching versus structural replacement

Most theme changes replace values and recipes while preserving component instances. A button keeps its key and interaction owner while its colors or motion profile change. Its draft-owning parent remains untouched.

Some languages need a different internal structure. A flat control might become a layered face-and-support implementation. Such replacement is allowed behind the same component contract, but requires explicit state and focus treatment. It is not equivalent to changing a CSS variable.

Transient contact state may be cancelled or simplified during the change. A user's typed value must be retained according to its state contract. An active input-method composition may require deferring replacement. The implementation should not silently destroy text merely because an appearance picker selected a more elaborate control.

Remote theme data can select approved recipe values and assets. Executable functions, arbitrary shaders and unrestricted platform code are not harmless token data. Their installation follows the graph's supported implementation-update boundary.

12.7 Theme scopes follow presentation ownership

A workbench may show its own chrome and several product previews at the same time. One global mutable theme cannot express this correctly. Each preview needs an effective scope, and menus or dialogs opened from it must retain that scope even if they are physically rendered elsewhere.

Figure 19. A portalled dialog can be placed outside its originating DOM region while retaining that region's theme ownership. Physical placement and logical scope are different relationships. See the illustrated PDF for the diagram.

On Compose, scoped providers supply the effective theme to a subtree. On the React web/JS path, context and scoped style variables provide the corresponding mechanism. The existing Reaktor React theme provider already illustrates the use of a wrapping scope rather than a document-global mutation. 14

A nested override should state exactly what it changes. A compact inspector may override density without changing the previewed product's brand. Non-negotiable accessibility constraints remain effective after local overrides.

12.8 Lowering recipes into each renderer

A neutral recipe does not mean Compose modifiers and CSS are interchangeable. Modifier order affects measurement, drawing and hit regions. CSS has its own layout and inheritance behavior. Each adapter lowers the same design intent into its toolkit's valid operations.

The React web renderer lowers typed recipe values into generated styles. A static styling tool such as StyleX is an optional implementation choice, not a renderer target or prerequisite. Dynamic values and runtime interaction still need explicit treatment. Arbitrary Kotlin code is not automatically convertible into static CSS. Manna maintains Kotlin recipes rather than a separate authored stylesheet. 15

Recipes name the exact channels eligible for animation. A blanket transition on every property can animate geometry unintentionally and complicate performance. Palette-only changes should not cause media to reload. Typography changes should invalidate measurement because pretending the old geometry remains valid would produce stale layout.

The theme system is successful when a new language changes the experience without changing component meaning, and when the inspector can explain both the selected values and the work their activation required.

13. Graph bindings, identity and lifecycle ownership

HLD — Arrows show ownership of mounts and leases. Repositioning a pane does not retire the business entry. Open the diagram for full size.

13.1 The graph describes application dependencies

A screen consumes application capabilities. A conversation timeline needs messages. A composer needs a draft and a send operation. A profile action needs a navigation binding. Reaktor's node-owned ports make these dependencies explicit rather than embedding service discovery inside drawing code. 6 16

Figure 20. The conversation owner exposes a model and operations through node-owned ports. The Surface boundary receives a checked projection instead of acquiring unrestricted access to every application object. See the illustrated PDF for the diagram.

The Surface integration layer resolves the relevant ports into a GraphBinding. That binding can use direct typed references in one runtime. It can use a qualified FFI realization when it crosses execution domains. The public operation remains the same conceptual capability; the connection mechanism is an implementation choice.

Inspection can then relate a control to the application operation it invokes. An agent or developer can ask which feature owns a draft or why an action is unavailable. This is more useful than inferring business dependencies from a visual tree.

13.2 Identity has several independent meanings

A component definition identifies a kind of control. A component instance key identifies one occurrence. A route entry identifies a particular navigation occurrence. A mount identifies one presentation attachment. A boundary generation identifies one active implementation binding.

These identities must not be collapsed into one integer called id. A theme revision can change without changing a route entry. Two windows can share a business object while having different mounts. A compact host handle can be reused internally, but it cannot become a stable external identity without generation checks.

The graph already contains route-entry identity. Surface should use that identity instead of inventing a parallel navigation system. The existing BackStackEntry contract is a useful integration seam. 17

A deterministic inspection document also needs explicit ordering. A concurrent collection's current iteration order is not a persistent identity or a guaranteed declaration order. Stable IDs and a reproducible export order have different jobs. 18

13.3 The same business object can be presented more than once

Suppose a conversation is open in a main window and a detached window. The messages can share an application owner. The views should not share keyboard focus or scroll position merely because they refer to the same conversation.

Figure 21. Business identity can be shared while each mount owns its own presentation state. A shared draft additionally requires an explicit multi-editor policy; sharing data does not define that policy automatically. See the illustrated PDF for the diagram.

The draft requires a deliberate decision. It can be shared by account and conversation, with conflict handling for simultaneous edits. It can be isolated per composition session if that is the product's intended behavior. The architecture should make the choice visible rather than accidentally using whichever singleton happens to be available.

A separate route key alone is not sufficient. If both views write the same mutable active-chat binding, they are still sharing one stateful slot. Entry-aware content and keyed session ownership are prerequisites for correct simultaneous presentation. The existing route-binding and chat-session implementations make this a concrete integration concern. 19 20

13.4 Existence, visibility, focus and interactivity are distinct

An application feature can exist while none of its views is visible. A hidden view can remain mounted to preserve selected presentation state. An outgoing screen can be visible during an exit animation but no longer admit new operations. A visible pane can be unfocused while another pane receives the keyboard.

These distinctions should be represented directly. One isActive boolean is usually too ambiguous to drive resource cleanup, navigation and input admission safely.

Figure 22. Application, workflow, composition and resource lifetimes overlap. A pane can disappear and return while the retained draft and conversation session continue to exist. See the illustrated PDF for the diagram.

The renderer uses visibility to pause decorative work and manage expensive resources. Focus controls relevant input routing. Interactivity controls whether the current presentation can admit operations. The graph owner determines the feature's actual lifetime.

This separation also makes testing clearer. Hiding a pane should stop its unnecessary frame work. It should not close a conversation session unless the product explicitly ties that session to visibility. Closing the feature can release the session without deleting durable conversation history.

13.5 Composition lifetime is not application lifetime

Compose and React both provide local state tied to their composition structures. That is useful for short-lived UI details, but it is not automatically the correct place for a draft that must survive layout changes. Compose's state-hoisting guidance distinguishes UI-element state from longer-lived business state; React's state preservation depends on component identity in the rendered structure. 21 22

Surface places retained workflow state outside replaceable presentation branches. A local checkbox animation can remain in the component. A multi-step event draft belongs to an explicit workflow owner. The distinction should be based on required lifetime, not on a rule that all state must be global.

Effects also have owners. Starting a connection inside a composable body is unsafe because composition can run again. Lifecycle-aware effect mechanisms exist to attach work to an appropriate scope, but their scope must still match the intended application lifetime. 23

13.6 Platform lifecycle cannot be flattened completely

Android can recreate an activity in response to configuration changes. A browser can hide, freeze or discard a page. Desktop and mobile hosts have different window and process relationships. These platform events do not form one identical lifecycle enum, and a final cleanup callback cannot be assumed to run in every termination case. 24 25

The portable layer therefore expresses required policies rather than pretending platform events are identical. It can say that visible animation pauses when presentation is suspended, or that a draft must be persisted after meaningful edits. Platform adapters map those requirements to their actual lifecycle facilities.

Persistence is separate from lifetime. A graph-owned object can outlive a view but still disappear if the process terminates. If the product promises recovery after process loss, the relevant state needs a storage contract. Keeping it in a longer-lived in-memory owner does not provide durability by itself.

13.7 Resource leases make cleanup explicit

A resource lease records that a scope is using something expensive or externally managed. Examples include a decoded image, a native editor instance, a platform observer and a field participant registration.

When the scope closes, its leases are released. An underlying cache may retain reusable data under a byte budget, but that is not the same as a forgotten reference keeping the entire view alive. Cleanup should be idempotent so repeated closure cannot corrupt resource accounting.

For asynchronous work, cancellation also has cleanup obligations. A superseded decode may have allocated a buffer. A cancelled host preparation may have created callback entries. Moving work off the UI thread does not remove the need to release those resources.

The useful invariant is simple: every retained object has an owner, and every owner has a defined point at which it stops retaining the object. Performance and correctness both become easier to reason about when this is explicit.

HLD — Arrows show inputs to presentation policy and the resulting placements. Usable environment inputs still need target integration. Open the diagram for full size.

14.1 Adaptation begins with a question about the task

An adaptive layout is not just a different number of columns. It changes how much of a task is visible at once. A compact conversation interface prioritizes the current conversation. A larger window can show the list beside it. A still larger workspace can add a supporting event or profile region.

The task remains coherent because the underlying state is shared through its proper owners. The layout exposes more context instead of creating a different application workflow whenever the width changes.

Figure 23. Compact, medium and expanded presentations expose different amounts of context. These are illustrative allocations: actual pane selection follows measured constraints, content needs and user preferences rather than device names alone. See the illustrated PDF for the diagram.

The canonical list-detail, supporting-pane and feed patterns are useful starting points. They encode common relationships between content regions. Their value is not that every application must look alike, but that the layout policy can express a recognizable task structure. 2

14.2 Window environment and container constraints

The window environment describes the host: logical dimensions, insets, input capabilities, text preferences and relevant posture information. Container constraints describe the space assigned to a particular component.

The record expresses the conceptual information the policies require. A platform adapter may preserve additional text-scaling or posture information where a single scalar is not sufficient. Such information belongs to a declared capability rather than being discarded to fit a falsely universal model.

A desktop inspector can receive a narrow allocation inside a large window. Its layout uses that allocation. It should not render a wide table because the outer window is classified as expanded.

Figure 24. A large window can contain a narrow region. The shell responds to window conditions; each component measures and adapts within its actual container. See the illustrated PDF for the diagram.

Android's window-size guidance treats these classes as dynamic properties of application space. Surface uses them for broad policy decisions, while actual constraints determine whether the content fits. 26

14.3 A pure policy chooses a presentation plan

The presentation policy reads navigation, constraints and preferences. It returns a plan describing visible entries, their pane roles and focus relationships.

A richer implementation can add minimum widths, overlays and collapse priorities. The important rule is that the result remains a presentation plan. The policy does not push or pop routes while measuring a pane.

Figure 25. Navigation remains graph-owned. The presentation policy determines how existing entries appear within the available space. A resize changes pane allocation without silently adding history. See the illustrated PDF for the diagram.

This design avoids feedback loops. If layout both reads and mutates navigation, a resize can repeatedly change the very state being laid out. Pure planning allows deterministic tests: given these entries and constraints, this arrangement is selected.

14.4 Content determines whether an arrangement is usable

A nominal breakpoint is not sufficient to prove that content fits. A translated title may be longer. A larger text preference may increase a form's minimum width. A resizable inspector may leave less room for the main panel.

The shared policy can define preferred and minimum pane widths, collapse order and available arrangements. The platform layout engine performs actual measurement. If constraints cannot be satisfied, the plan can reduce simultaneous panes or use an alternate presentation.

This does not require inventing a universal layout solver. Compose and the web already have capable layout mechanisms. Surface shares the task-level policy and the meaning of layout primitives, then qualifies how each renderer realizes them. Intrinsic measurement and text shaping remain platform work. 27

A back action can close a modal, dismiss a supporting sheet or pop a route entry. These are not always interchangeable. The presentation layer identifies the currently relevant input scope, but navigation authority remains in the graph.

For a compact layout, a supporting profile may occupy a foreground route. In an expanded layout it may be visible beside the conversation. The application must define whether Back removes the supporting entry, changes focus or navigates elsewhere. Merely moving the view into a side panel should not invent a new history.

Web realization must also preserve browser history and link behavior. These are platform semantics, not visual effects. A theme cannot change whether a resource is navigable, and a decorative transition cannot be the sole mechanism that completes a route result.

14.6 UI scale, text scale, density and canvas zoom

Several values can make something appear larger, but they mean different things. Pixel density maps logical drawing units to physical pixels. UI zoom changes the logical amount of space available to application chrome. Text scaling follows the user's reading needs. Canvas content zoom changes a document or graph viewport.

Applying the same multiplier at several levels creates errors. A popup can be displaced, a hit region can fail to match its visible control, or an image can decode at an unnecessarily large size. The adapter must specify which coordinate system each value uses and which transforms have already been applied.

Figure 26. Input origins, effect fields, drawing pixels and shader coordinates belong to different spaces. Explicit transforms keep feedback, hit testing and overlays aligned through scrolling, resizing and zoom. See the illustrated PDF for the diagram.

A 125% workbench zoom should normally affect layout and usable logical space. Scaling only the final drawing layer can leave input and accessibility geometry behind. A graph's pan and zoom remain separate content transforms so the workbench controls do not grow every time the graph is magnified.

14.7 Layout stability is a contract for asynchronous content

An image can arrive after surrounding text is measured. A font can load after a fallback has been used. A generated region can become available after the user begins reading. These changes are normal; unexpected movement of the user's target should not be the default consequence.

Media reserves dimensions or aspect ratio before loading when that information is known. Placeholders approximate the expected structure. Collections restore position using item identity and relative offset rather than only a global pixel coordinate.

The invariant is not that nothing ever moves. Larger text and translated content legitimately require reflow. The invariant is that the system anticipates asynchronous geometry where possible and preserves a meaningful anchor when geometry must change.

For a conversation, the anchor can be the message being read. For a form, it can be the active field. For a graph, it can be the selected node's relationship to the viewport. Each is more meaningful than assuming an old absolute offset remains correct after all layout inputs change.