v0.2.2

Component atlas

The component atlas is a build-time reference for individual components: what each is really for, the states and edge cases it needs, how it should behave, and how to test it. It is consulted once a direction is set. It is not a source of designs: a component's form comes from the project's device, and the atlas makes sure the result is complete and correct.

How it is organised

180 components in 12 sections:

§SectionExamples
1Global layout and compositionPage templates, section sequencing, grids, editorial layouts
2NavigationMain navigation, mega menus, breadcrumbs, scroll-aware navigation
3Heroes and opening experiencesTypography-led heroes, product demonstrations, data-driven openings
4Typography and contentDisplay headings, numeric displays, kinetic typography, microcopy
5Action and form controlsButtons, comboboxes, sliders, file upload, multi-step forms
6Repeated content structuresCards, accordions, carousels, pricing tables, testimonials
7Complex data interfacesData grids, charts, filters, command menus, dashboard panels
8Feedback and system statesSkeletons, empty states, errors, toasts, dialogs
9Product-specific experiencesOnboarding, sign-in, checkout, product configuration
10Experimental and custom interactionsDrag, infinite canvases, scroll-driven scenes, WebGL environments
11Mobile-specific componentsBottom sheets, swipe, sticky mobile actions, mobile filters
12Footer and secondary detailsFooters, cookie preferences, error and maintenance pages

The entry format

Every entry answers the same fields in the same order, so a search returns a whole entry:

FieldMeaning
JobWhat the component is really for
GenericThe common default, and Why it fails (generic, timid, unresolved, incoherent or unverified)
StrongerWays out, to be re-derived from this project's content and device. Never designs to adopt
Keep convention whenContexts where the familiar pattern is right
DecideHow to choose
Content · Motion · Responsive · A11yRequirements
StatesStates and edge cases to build
BuildImplementation notes
Test · Severity · EvidenceHow to verify; A is a review trigger and C a failure if violated; research ledger IDs
ExampleA generic version and a context-specific replacement

A few entries are cross-references: one line pointing to the entry or reference that covers the component, with its own severity and evidence. tests/test_library.py checks that every entry is complete or a cross-reference, that fields are in order, that severities are A or C, that cross-references point at real entries, and that the index at the top of the atlas lists every entry.

Searching it

The atlas is searched, never read whole:

grep -n "^### " skills/form-and-force/references/component-atlas.md                  # every component
grep -n "^### " skills/form-and-force/references/component-atlas.md | grep -i pricing
grep -n -A 16 "^### Pricing tables" skills/form-and-force/references/component-atlas.md

On the documentation site, the search box finds components by name and by the text of their entries.

Index

Generated from the atlas by tooling/sync_docs.py; do not edit by hand.

<!-- generated:atlas-index --> 180 components.

SectionComponentSeverityJob
1. Global layout and compositionPage templatesAGive each page type a predictable skeleton so users learn the site, while leaving room for content-specific composition.
1. Global layout and compositionHeader and footer compositionA (C if focus is obscured)Brand presence, orientation and access to primary routes (header); completion, secondary routes, trust and legal (footer).
1. Global layout and compositionSection sequencingAOrder sections so each answers the question the previous one raised.
1. Global layout and compositionGrids and asymmetric layoutsACreate a recognisable spatial logic that organises content and gives the brand a structure.
1. Global layout and compositionWhitespace and information densityAControl attention and scanning speed; fit density to the task.
1. Global layout and compositionEditorial layoutsAMake long reading pleasurable and let images and annotations argue alongside the text.
1. Global layout and compositionFull-bleed contentAGive the most important visual its full frame; create pacing breaks.
1. Global layout and compositionOverlapping and layered compositionsAExpress relationships (annotation on object, caption on image, depth in a scene).
1. Global layout and compositionBackground graphicsAAtmosphere and identity behind content, carrying the concept's material.
1. Global layout and compositionResponsive compositionC if broken (overflow, lost content); A otherwiseKeep the composition's idea intact as space changes.
1. Global layout and compositionLong-form page flowAKeep users oriented and moving through long pages.
2. NavigationUtility barsASecondary, task-oriented links (locale, account, support, store finder) above the main nav.
2. NavigationMain navigationC if not keyboard-operableShow what the site contains and where the user is; let them move between top-level areas.
2. NavigationTransparent and sticky headersC for obscured focusKeep navigation reachable without stealing content space; let hero imagery breathe.
2. NavigationMinimal navigationAReduce chrome for immersive or single-purpose experiences.
2. NavigationFull-screen menusC if focus escapes or hides behindPresent navigation as an event: a large index, often with previews.
2. NavigationMega menusA (C if hover-only)Expose a large IA (dozens of destinations) in one view.
2. NavigationSidebarsAPersistent navigation for apps, docs and dashboards.
2. NavigationBreadcrumbsAShow location in a deep hierarchy and allow quick ascent.
2. NavigationNavigation drawersC (focus on hidden links)Off-canvas navigation on small screens or secondary panels.
2. NavigationTab barsAPrimary destinations in app-like mobile experiences.
2. NavigationFloating navigationAKeep navigation available as a compact, persistent element.
2. NavigationMobile navigationC if inaccessibleFast access to destinations on small, touch screens.
2. NavigationScroll-aware navigationAAdapt navigation to reading context (condense, hide, show progress).
2. NavigationActive states and orientation cuesC if location is invisible to assistive techTell users where they are and what's selected.
3. Heroes and opening experiencesStandard heroesAState what this is and for whom, and offer the next step, within the first screen.
3. Heroes and opening experiencesSplit-screen compositionsAPair two things that belong together (text and object, before and after, two audiences).
3. Heroes and opening experiencesAsymmetric heroesACreate tension and focus through imbalance.
3. Heroes and opening experiencesTypography-led heroesALet words carry identity when the message is the product (editorial, studios, manifestos).
3. Heroes and opening experiencesImage-led heroesA (C if fabricated imagery is presented as real)Let a real image establish place, product or mood immediately.
3. Heroes and opening experiencesProduct demonstrationsC if fakeShow the product doing its job in seconds.
3. Heroes and opening experiencesInteractive canvasesA (C if it gates content without an alternative)Invite manipulation as the first act (configure, draw, explore).
3. Heroes and opening experiencesData-driven openingsC if unsourced or inventedOpen with a real number or visualisation that frames the story.
3. Heroes and opening experiencesEditorial introductionsAOpen a story with voice, context and an invitation to read.
3. Heroes and opening experiencesFull-screen experiencesC if content is unreachable without the experienceImmerse the visitor in a world from the first frame.
3. Heroes and opening experiencesPreloaders and entry transitionsC (fake percentages); A otherwiseBridge real loading time, or mark a deliberate threshold.
4. Typography and contentDisplay headingsAEstablish voice and hierarchy at the largest scale.
4. Typography and contentBody textC if contrast failsComfortable, sustained reading.
4. Typography and contentCaptions and metadataA (C if contrast fails)Context (source, date, author, credit) without competing with content.
4. Typography and contentLabelsAName UI elements and categories precisely.
4. Typography and contentTechnical annotationsC if specs are wrongExplain parts, measurements or behaviour directly on a visual.
4. Typography and contentNumeric displaysAPresent numbers so they can be read and compared.
4. Typography and contentVariable fontsAFine typographic control and expressive behaviour from one file.
4. Typography and contentKinetic typographyA (C if text becomes unreadable to assistive tech)Make words move when their movement is the message.
4. Typography and contentText wrapping and measureC if overflow; A otherwiseKeep lines readable and headlines well-shaped.
4. Typography and contentEditorial hierarchyAGuide readers through levels (kicker, title, deck, subheads, body, notes).
4. Typography and contentRich textC for unsanitised inputRender CMS or markdown content consistently and safely.
4. Typography and contentMicrocopyAMake actions, errors and states unambiguous.
4. Typography and contentEmpty or missing copyCHandle content that doesn't exist yet without breaking the layout or lying.
4. Typography and contentContent placeholdersCStand in for real assets during design without misleading anyone.
4. Typography and contentMultilingual and localisationA (C if a supported locale breaks)Work in every supported language and script.
5. Action and form controlsButtonsC if non-functional or not keyboard-operableTrigger an action with a clear consequence.
5. Action and form controlsButton groupsAOffer related actions or exclusive options together.
5. Action and form controlsIcon buttonsC if unnamedCompact, frequent actions (close, edit, more).
5. Action and form controlsLinksC for dead linksNavigate to a resource.
5. Action and form controlsInput fieldsC if unlabelledCapture text accurately and quickly.
5. Action and form controlsSearch fieldsC if fakeFind content or items fast.
5. Action and form controlsSelect menusC if inaccessibleChoose one option from a list.
5. Action and form controlsComboboxesC if not operableChoose from a large or searchable set; allow free entry where appropriate.
5. Action and form controlsCheckboxesC for pre-checked consentToggle independent options; agree to terms.
5. Action and form controlsRadio groupsC if inaccessibleChoose exactly one of a few options.
5. Action and form controlsSwitchesA (C if decorative)An immediate on/off setting.
5. Action and form controlsSlidersC if not operableChoose a value in a range where approximate selection is fine.
5. Action and form controlsFile upload controlsC if drag-onlyAdd files reliably.
5. Action and form controlsValidation messagesC if errors aren't perceivableHelp users fix errors.
5. Action and form controlsMulti-step formsC if data lossBreak long tasks into manageable steps.
5. Action and form controlsSubmit statesC if double submission is possible on paymentsConfirm that an action is in progress and then done.
5. Action and form controlsConfirmation flowsAPrevent costly mistakes without nagging.
5. Action and form controlsDestructive actionsC if no safeguard on irreversible dataRemove or irreversibly change data safely.
5. Action and form controlsDisabled statesAShow that an action isn't available.
6. Repeated content structuresFeature gridsACommunicate what the product does.
6. Repeated content structuresCardsAPackage one item for scanning and selection.
6. Repeated content structuresList rowsADense scanning of many items.
6. Repeated content structuresAccordionsALet users reveal details on demand.
6. Repeated content structuresTabsC if inaccessibleSwitch between peer views of the same context.
6. Repeated content structuresCarouselsC if auto-moving without pauseBrowse a set where only some items fit.
6. Repeated content structuresGalleriesA (C if the lightbox traps or fails keyboard)Present visual work at quality.
6. Repeated content structuresContent feedsAContinuous discovery of new items.
6. Repeated content structuresTimeline layoutsAShow events in temporal order and their relationships.
6. Repeated content structuresPricing tablesC if the claim is fabricatedHelp buyers choose a plan with confidence.
6. Repeated content structuresTestimonialsC if inventedBorrow credibility from real customers.
6. Repeated content structuresClient logo displaysC if fabricatedSignal adoption by recognisable organisations.
6. Repeated content structuresMetrics and statisticsC if unsourcedQuantify impact credibly.
6. Repeated content structuresCase-study showcasesADemonstrate thinking and outcomes.
6. Repeated content structuresProduct comparisonsC if false claimsHelp choose between options.
6. Repeated content structuresRelated contentAContinue the journey.
7. Complex data interfacesTablesA (C if inaccessible)Compare records across attributes.
7. Complex data interfacesData gridsC if broken keyboardEdit and manipulate tabular data (spreadsheet-like).
7. Complex data interfacesChartsC if the data is fake and presented as realReveal patterns in data for a specific question.
7. Complex data interfacesKPIsA (C if fake)Surface the few numbers that indicate health, with context.
7. Complex data interfacesFiltersC if they don't filterNarrow a set to relevant items.
7. Complex data interfacesSort controlsAReorder results by a chosen attribute.
7. Complex data interfacesSearch and query buildersAExpress complex queries.
7. Complex data interfacesPaginationANavigate large result sets.
7. Complex data interfacesActivity feedsC if fakeShow what happened, by whom, when.
7. Complex data interfacesCommand menusAFast keyboard access to actions and navigation.
7. Complex data interfacesDashboard panelsA (C if fake data presented as real)Group related metrics or views on one screen.
7. Complex data interfacesSide-detail inspectorsAView and edit an item's details without losing list context.
7. Complex data interfacesMonitoring interfacesADetect anomalies and respond.
7. Complex data interfacesMulti-step configurationASet up complex objects (integrations, products, plans).
7. Complex data interfacesBulk actionsAAct on many items at once.
7. Complex data interfacesSaved viewsAReturn to a configured perspective quickly.
7. Complex data interfacesData exportC if fakeGet data out in useful formats.
7. Complex data interfacesNotification systemsAInform users about events that need attention.
8. Feedback and system statesLoading statesACommunicate that work is happening and roughly how long it'll take.
8. Feedback and system statesSkeletonsAPreview layout while content loads to reduce perceived wait and CLS.
8. Feedback and system statesProgress indicatorsC if fakeShow completion of a known-length task.
8. Feedback and system statesEmpty statesAExplain why there's nothing and what to do.
8. Feedback and system statesErrorsC if errors are silentExplain failures and how to recover.
8. Feedback and system statesSuccess messagesAConfirm an outcome and point to what's next.
8. Feedback and system statesWarningsAAlert users before a problem happens.
8. Feedback and system statesToast notificationsATransient, non-blocking confirmation.
8. Feedback and system statesDialogsC if focus escapesFocused tasks or information that require attention.
8. Feedback and system statesConfirmation modalsASee the entry
8. Feedback and system statesTooltipsC if essential info is hover-onlyBrief supplementary hints.
8. Feedback and system statesPopoversASmall interactive panels anchored to a trigger (menus, pickers).
8. Feedback and system statesOffline statesA (C for data loss)Keep users informed and productive without a network.
8. Feedback and system statesRetry flowsARecover from transient failures.
8. Feedback and system statesPermission failuresAExplain why access is denied and how to get it.
8. Feedback and system statesAuthentication expiryC if work is lostRe-authenticate without losing work.
8. Feedback and system statesUnsaved changesA (C if silent data loss)Prevent accidental loss of edits.
8. Feedback and system statesPartial failuresC if misreportedReport mixed results honestly.
9. Product-specific experiencesOnboardingAGet new users to first value fast.
9. Product-specific experiencesSign-up and sign-inC if inaccessible authenticationCreate or access an account with minimum friction and maximum trust.
9. Product-specific experiencesFirst-run guidanceAOrient users in an empty product.
9. Product-specific experiencesSettingsC if settings do nothingLet users configure the product confidently.
9. Product-specific experiencesPreferencesAPersonalise the experience (theme, density, motion, language).
9. Product-specific experiencesUser profilesARepresent a person and let them manage their identity.
9. Product-specific experiencesPermissionsC if the UI misrepresents real permissionsControl who can do what.
9. Product-specific experiencesBillingC for roach-motel cancellationMake cost, usage and payment transparent.
9. Product-specific experiencesCheckoutC for broken or deceptive stepsComplete a purchase quickly and safely.
9. Product-specific experiencesShopping cartsC for fake urgencyReview and adjust before buying.
9. Product-specific experiencesProduct configurationA (C if the preview misrepresents the product)Let buyers build the right variant and see it.
9. Product-specific experiencesSearch and discoveryAHelp users find what they want, or discover what they didn't know.
9. Product-specific experiencesFilters and sortingC if non-functionalSee the entry
9. Product-specific experiencesSaved itemsALet users bookmark for later.
9. Product-specific experiencesAccount managementAManage email, password, sessions, data and deletion.
9. Product-specific experiencesAI-assisted interfacesA (C if outputs are presented as verified fact)Help users accomplish tasks with AI while keeping them in control.
9. Product-specific experiencesConversational interfacesAComplete tasks through dialogue.
9. Product-specific experiencesCode editorsAWrite and read code comfortably.
9. Product-specific experiencesVisual workflow buildersC if drag is the only pathCompose logic visually (nodes and edges).
10. Experimental and custom interactionsCursor-following graphicsAAdd presence or reveal content near the pointer.
10. Experimental and custom interactionsMagnetic interactionAMake targets feel physical and easier to hit.
10. Experimental and custom interactionsHover revealsC if essential info is hover-onlyShow secondary content on intent.
10. Experimental and custom interactionsDrag interactionsC if drag-onlyDirect manipulation: reorder, scrub, move, compare.
10. Experimental and custom interactionsInfinite canvasesA (C without an accessible equivalent)Explore large spatial collections.
10. Experimental and custom interactionsSpatial navigationC if content is unreachable without spatial navigationNavigate content as places.
10. Experimental and custom interactionsInteractive mapsA (C if scroll is trapped)Explore location-based information.
10. Experimental and custom interactionsScroll-driven scenesA (C if content is unreachable or scroll is trapped)Explain mechanisms or tell stories in sequence. Generic: Pinned sections with unrelated parallax layers; fade-up everything. Stronger: Scrub that explains a mechanism (photo → digital twin); text leads; short pins; a static equivalent. Severity: A (C if content is unreachable or scroll is trapped). Evidence: corpus §6, §7.
10. Experimental and custom interactions3D object manipulationAInspect a product or object from all sides.
10. Experimental and custom interactionsWebGL environmentsC if no fallback hides essential contentSee the entry
10. Experimental and custom interactionsAudio-reactive visualsC if audio autoplays or flashesMake sound visible or sound-led experiences expressive.
10. Experimental and custom interactionsGenerative patternsACreate unique, systematic visuals (per user, per item, per data point).
10. Experimental and custom interactionsInteractive storytellingALet the audience participate in a narrative.
10. Experimental and custom interactionsCustom mobile widgetsATouch-native interactions specific to the product.
10. Experimental and custom interactionsUnconventional menusANavigation that expresses the concept.
10. Experimental and custom interactionsSignature navigation systemsANavigation that becomes the experience's identity.
11. Mobile-specific componentsTouch-first navigationAReach key destinations with a thumb.
11. Mobile-specific componentsMobile cards and listsAScan items on small screens.
11. Mobile-specific componentsSwipe interactionsC if swipe is the only pathFast actions and browsing by gesture.
11. Mobile-specific componentsBottom sheetsA (C if it traps)Contextual panels on mobile (filters, options, details).
11. Mobile-specific componentsMobile filtersARefine results on small screens.
11. Mobile-specific componentsExpandable detailsAHide secondary information until needed on small screens.
11. Mobile-specific componentsSticky mobile actionsC if it obscures focusKeep the primary action reachable (add to cart, book, apply).
11. Mobile-specific componentsResponsive mediaAImages and video that fit and perform on small screens.
11. Mobile-specific componentsGesture alternativesCMake gesture-driven features usable by everyone.
11. Mobile-specific componentsTouch-friendly data viewsARead and act on data on phones.
11. Mobile-specific componentsReduced-motion behaviour (mobile)CRespect motion preferences on devices where vestibular effects are strongest (motion close to the eyes, while moving).
11. Mobile-specific componentsMobile-specific content hierarchyAPut the most important thing first on small screens.
12. Footer and secondary detailsFootersA (C if links are dead)Close the experience: next step, orientation, trust, legal.
12. Footer and secondary detailsLegal navigationC if placeholder legal content shipsAccess privacy, terms, imprint and accessibility statement.
12. Footer and secondary detailsContact informationC if the form is fakeLet people reach the organisation.
12. Footer and secondary detailsSocial linksC if deadConnect to active channels.
12. Footer and secondary detailsBack-to-top actionsAReturn to the top of long pages.
12. Footer and secondary detailsCookie preferencesC for deceptive patternsObtain lawful, informed consent without ruining the first impression.
12. Footer and secondary detailsError pagesARecover from 404 and 500 gracefully.
12. Footer and secondary detailsMaintenance pagesACommunicate downtime.
12. Footer and secondary detailsSearch resultsAPresent matches so users can choose quickly.
12. Footer and secondary detailsNo-results statesARecover from searches or filters that return nothing.
12. Footer and secondary detailsConfirmation pagesA (C if refresh re-submits a payment)Confirm completion and set expectations.

<!-- /generated -->