Document theme builder integration guide

epic-visual-design-accessibility-theme-integration-task-010 — Write the developer integration guide for the AccessibleThemeBuilder covering: how to add a new organisation's branding config, the override validation flow and error handling contract, the Riverpod provider graph showing theme builder dependencies, and a troubleshooting section for common debug-mode assertion failures. Include code samples demonstrating correct MaterialApp wiring and organisation context switching.

medium priority low complexity documentation pending documentor Tier 9

Acceptance Criteria

The guide includes a 'How to add a new organisation' section with numbered steps covering: creating the OrganisationBrandingConfig entry, registering the config in the provider, adding design tokens to the token JSON file, running the contrast validator, and writing the required unit tests

The override validation flow section explains: what inputs are validated, what the error/fallback contract is when validation fails (fallback to base token vs. throw), and what debug-mode assertions are triggered, with the exact assertion message text so developers can recognise them in the console

A Riverpod provider dependency graph (text-based ASCII or Mermaid diagram) is included showing the dependency chain from activeOrganisationProvider → AccessibleThemeBuilder → MaterialApp

The MaterialApp wiring code sample is complete, compilable Dart showing the ConsumerWidget wrapper, the ref.watch call, and both theme and darkTheme properties assigned from provider output

The organisation context switching code sample shows how to call the provider notifier to change the active org and confirms that no additional widget-tree manipulation is required

The troubleshooting section covers at least the following scenarios: 'Assertion failed: contrast ratio < 4.5', 'ThemeData is null on first frame', 'Theme does not update after org switch', and 'Missing token key' — each with root cause and fix

All code samples in the guide compile without errors against the current codebase (verified by pasting into a scratch Dart file or a dedicated documentation test)

The guide is written in English and stored in the agreed project documentation location (e.g., `docs/theme-builder-integration.md` or inline in the package README)

A peer developer unfamiliar with the ThemeBuilder can follow the guide to add a fifth fictitious organisation config end-to-end without asking for additional help

Technical Requirements

frameworks

Flutter (code samples target the current Flutter SDK version used in the project)

Riverpod (provider graph and wiring examples)

Dart (all code samples must be valid Dart)

apis

AccessibleThemeBuilder public API (all public methods and constructors must be documented)

Riverpod ProviderRef and Notifier APIs as used in wiring samples

MaterialApp theme/darkTheme constructor parameters

data models

OrganisationBrandingConfig (document all required and optional fields with types and constraints)

ThemeBuilderState (document the output shape)

DesignToken (document the JSON schema for the token file)

performance requirements

Documentation build (if using a doc generator) must complete in < 30 seconds

Code samples must not include anti-patterns that would cause jank (e.g., constructing ThemeData inside build())

security requirements

Code samples must not log or expose sensitive org configuration data

The guide must note that branding configs should not contain credentials or secrets

Execution Context

Execution Tier

Tier 9

Tier 9 - 22 tasks

Can start after Tier 8 completes

Integration Task

Handles integration between different epics or system components. Requires coordination across multiple development streams.

View Full Execution Plan

Implementation Notes

Write the guide as a Markdown file co-located with the theme builder source (e.g., `lib/src/theme/README.md`) or in a top-level `docs/` directory depending on project convention — check existing documentation placement before deciding. Use Mermaid for the provider dependency graph if the project's documentation renderer supports it (GitHub renders Mermaid natively); otherwise use ASCII art. Structure the document with the most common task first ('Add a new organisation') so developers find the answer immediately without reading the full guide. Keep code samples minimal — show only what is needed to illustrate the point and use `// ...

existing code` comments to elide boilerplate. For the troubleshooting section, write each entry as: **Symptom** (exact console output or visible behaviour) → **Root cause** (one sentence) → **Fix** (numbered steps). Include a 'Quick reference' table at the top mapping provider names to their purpose — this serves as a fast lookup for developers who already know the system. Cross-reference the test file written in task-009 so developers know where to find examples of correct usage in a test context.

Testing Requirements

Documentation testing: extract all Dart code samples from the guide and run them through `dart analyze` to confirm zero analysis errors. Run `dart format --output=none --set-exit-if-changed` on code samples to confirm they follow project formatting conventions. Manual review test: a developer not involved in the ThemeBuilder implementation should attempt to follow the 'add a new organisation' steps on a branch and report any steps that were unclear or missing. Any gaps found during review must be addressed before the guide is merged.

Verify the Riverpod provider graph is accurate by comparing it to the actual provider definitions in the source files — outdated graphs are worse than no graph.

Component

Accessible Theme Builder

infrastructure medium

Dependencies (1)

Write unit tests covering: token-to-ColorScheme mapping for all four organisations in both light and dark modes, rejection of brand overrides that fail contrast validation, and correctness of all component theme factory outputs. Add widget tests that mount a minimal MaterialApp with each org ThemeData and assert that rendered text and button widgets pass contrast and touch target checks using the accessibility test harness. epic-visual-design-accessibility-theme-integration-task-009

Epic Risks (2)

high impact low prob scope

One or more of the four partner organisations may supply brand primary colors that cannot be paired with any standard foreground at 4.5:1 contrast (for example, a mid-range hue that is too light for dark text and too dark for white text). Rejecting these colors programmatically could cause a political dispute with the organisation and delay the feature.

Mitigation & Contingency

Mitigation: Before implementation begins, run all four organisations' existing brand primary colors through the contrast-ratio-validator against both white (#FFFFFF) and a near-black (#1A1A1A). Share the results with each organisation's contact person ahead of the theme builder sprint so any problematic colors can be adjusted collaboratively with advance notice.

Contingency: If an organisation insists on a non-compliant brand color, produce a compliant near-match (lightened or darkened along the hue's luminance axis) and present both options with contrast ratio evidence. Document the adjusted token in the manifest with an explicit note that the original brand color was non-compliant, and obtain written sign-off from the organisation.

medium impact medium prob scope

Flutter's ThemeData contains over 30 component theme properties. If the theme-builder only addresses the most common ones (Button, InputDecoration, Card) and leaves others at Flutter defaults, downstream feature teams may unknowingly use default-themed widgets that do not meet sizing or contrast requirements.

Mitigation & Contingency

Mitigation: Produce a full inventory of all ThemeData component theme properties and map each to either a token-driven override or an explicit pass-through decision documented in the theme builder code. Prioritise the inventory by frequency of use in the existing codebase (identified via Grep). Include a check in the CI lint runner that flags widgets using Flutter default component themes not covered by the theme builder.

Contingency: If the full inventory scope exceeds the sprint budget, ship with the highest-frequency components covered and add a tracked backlog item for each uncovered component theme, pairing with a temporary lint suppression comment that includes the backlog reference.

Quick Links

All Tasks Execution Plan