00 / Source of truth

Agent implementation guide

The rules future agents must follow to build Mufflermen interfaces with the same light/dark material profiles, app segmentation, accessibility, responsive behaviour and conversion polish.

Production answer

Agent implementation guide is a reusable Oak Flats Muffler Men UI primitive with documented states, accessibility expectations, theme behavior, and implementation evidence.

Primary CTAReview Agent implementation guide states
Generative search brief

Agent implementation guide: The rules future agents must follow to build Mufflermen interfaces with the same light/dark material profiles, app segmentation, accessibility, responsive behaviour and conversion polish.

Shared Core Primitives

Buttons, forms, selection controls, navigation, overlays, feedback, typography, icons, tokens, and motion used by every Mufflermen product.

shared tokensa11y firstbarrel imports

Website Primitives

Marketing pages, service pages, location pages, maps, banners, forms, conversion CTAs, email and campaign primitives for mufflermen.com.au.

conversionSEO pagesservice copy

Hermes Dashboard Primitives

Operator dashboards, KPIs, command surfaces, AI assistant, workflow builder, inbox, audit events, and marketing approval pipelines.

operator UIdense datacommand rail

Muffler Pulse / Postiz

Social composer, content calendar, approval flow, channel status, campaign analytics, notification inbox, and media preview states.

social automationcalendarchannels

Workshop Management

Quote builder, vehicle profile, fitment checks, job tickets, weld-bay allocation, front desk, technician mobile, CRM, invoices and print docs.

rego / VINfitmentjob flow

Parts System

Parts catalogue, product cards, supplier media, compatibility filters, shipping, cart, checkout, pricing, receiver dashboard and product search.

cataloguefitment searchcommerce

CMS / Agent UI

Payload CMS, Control OS, permissions, auth, account, KYC, production gates, AI task surfaces, citations, tools, and audit trails.

controlpermissionsagent notes

Marketing / Presentation

Approved logos, campaign visuals, hero images, social tiles, presentation examples, video loops, and reusable banner grammar.

brand assetslogospresentation
System readiness

Every product surface maps back to primitives

This is the handoff map future agents must use before touching product UI. It keeps website, Hermes, Pulse, workshop, parts, CMS and agent surfaces on the same token, QA and approval rails.

mufflermen.com.au

Public production website. Primitive changes must promote through task branch, PR, staging, browser QA, approval, then production.

Source route/ui-primitives/marketing/full-landing/ui-primitives/forms-gallery/ui-primitives/maps

QA: SEO surfaces, service copy, forms, maps, image sizing, tap targets, no dark/light bleed, Lighthouse 100 target.

Contract: Website primitives own public conversion grammar; do not let app-dashboard density leak into public pages.

Muffler Pulse / Postiz

Social automation surface only. Future publishing controls stay design-only until permissions and approvals are secured.

Source route/ui-primitives/notifications/ui-primitives/calendar/ui-primitives/brand-assets

QA: Composer, channel states, approval status, notification density, media previews, schedule cards and reduced motion.

Contract: Pulse primitives use warm campaign energy while preserving the same buttons, cards, tokens and focus states.

Hermes dashboard

Operator UI reference for authorised task intake, PR gates, staging deploys, browser QA and approval reporting.

Source route/ui-primitives/dashboards/ui-primitives/workflows/ui-primitives/production

QA: Dense data readability, command states, audit trail visibility, explicit approval language and no secret exposure.

Contract: Hermes primitives must never imply production can be deployed without human approval and gate evidence.

Workshop management

Internal job-flow surfaces for quoting, fitment, tickets, front desk, technician mobile and printable handoff docs.

Source route/ui-primitives/workshop/ui-primitives/crm/ui-primitives/print-docs

QA: Mobile technician widths, job-card density, print preview, high-contrast status chips, VIN/rego/SKU overflow.

Contract: Workshop primitives can be dense, but every state still needs clear hierarchy and keyboard-safe controls.

Parts system

Catalogue and ecommerce grammar for fitment search, product cards, compatibility filters, cart and checkout.

Source route/ui-primitives/commerce/ui-primitives/search/ui-primitives/marketing/full-landing

QA: Long SKU wrapping, product media fallbacks, filter controls, checkout steps, freight/payment clarity and Lighthouse blockers.

Contract: Parts primitives use green readiness signals without drifting away from Mufflermen chrome/glass material rules.

CMS / Control OS

Payload/CMS/admin primitives. Category indexes stay complete; implementation docs belong on detail routes.

Source route/ui-primitives/auth/ui-primitives/account/ui-primitives/kyc/ui-primitives/help-docs

QA: Auth and role semantics, KYC journey completeness, audit logs, account safety, no duplicate IDs and form labels.

Contract: Keep the fuller KYC index intact; add source-file guidance to detail pages instead of replacing catalogs.

Agent UIs

AI and agent task surfaces for prompts, tool calls, citations, conversation rails, approvals and QA evidence.

Source route/ui-primitives/inbox/ui-primitives/workflows/ui-primitives/qa

QA: Streaming states, citations, tool-call cards, keyboard traversal, reduced motion and audit-friendly status wording.

Contract: Agent primitives must surface evidence and approvals, not hide consequential automation behind decorative UI.

Future business platforms

Bootstrap grammar for future Telegram, Google Workspace, marketing and reporting platforms. Design only until secured.

Source route/ui-primitives/brand-assets/ui-primitives/qa/ui-primitives/production

QA: Explicit disabled states, permission language, approval copy, responsive matrices and asset-source traceability.

Contract: Future platforms inherit this source of truth first, then earn implementation only after security review.

Required primitive anatomy

  1. 1Live visual preview
  2. 2Intentional light mode example
  3. 3Intentional dark mode example
  4. 4Code block and setup instructions
  5. 5Usage, accessibility, responsive and token notes

Design DNA

Dark mode is obsidian, chrome, red paint, amber workshop light and instrument glass. Light mode is pearl enamel, frosted workshop glass, clean steel shadows and calibrated red/teal/green signals. Both modes use the same spacing, radius, typography and icon grammar.

Use: --primitive-red, --primitive-amber, --primitive-teal
Use: --primitive-panel, --primitive-line, --primitive-shadow-soft
Use: Anton display + mono micro labels
Avoid: one-off app palettes, generic SaaS copy, dark-only cards
Implementation source

Mufflermen site button

Use siteButton + variant classes from src/app/ui-primitives/ui-primitives.module.css. This card is the copy contract for agents building the same Mufflermen DNA elsewhere.

Source files

Routesrc/app/ui-primitives/actions/page.tsx
Componentsrc/app/ui-primitives/sections/actions-section.tsx
Stylessrc/app/ui-primitives/ui-primitives.module.css

Setup

  1. 1
    Use the shared class recipe

    Compose `siteButton` with `siteButtonRed`, `siteButtonChrome`, or `siteButtonGhost` so hover and focus states stay consistent.

  2. 2
    Keep action copy mechanical

    Use direct workshop verbs: inspect, quote, approve, schedule, fit, dispatch, publish.

  3. 3
    Render inside a glass panel

    Buttons are tuned for primitive panels that use `--primitive-panel`, `--primitive-line`, and shared neumorphic shadows.

Usage guidance

  • Primary actions use red/chrome contrast; secondary actions use ghost glass.
  • Avoid generic SaaS copy like Submit or Continue when a workshop-specific verb is available.
  • Use icons only when they clarify the action; keep arrow glyphs for forward conversion actions.

Accessibility notes

  • Buttons and links need visible text labels, not icon-only labels unless `aria-label` is present.
  • Focus-visible must remain stronger than hover.
  • Do not remove underline alternatives from links without a clear button affordance.

Responsive behaviour

  • Allow wrapping in `heroActions` and `buttonRow`.
  • Use min-height rather than fixed height so copy can localise safely.
  • On mobile, stack critical CTAs above decorative controls.

Required tokens

  • --primitive-red
  • --primitive-red-dark
  • --primitive-line-strong
  • --primitive-font-mono
  • --primitive-control-surface
  • --primitive-surface-shadow

Dependencies

  • next/link
  • lucide-react where icons are needed

AI agent notes

  • Keep the chrome/paint/glass feeling, not flat red SaaS buttons.
  • Use Oak Flats, NSW, rego, VIN, fitment, weld bay, Manta, Hilux and Ranger copy where relevant.
  • Never create a one-off button style for an app section without mapping it back to these tokens.

Minimal usage

TSXexample-button.tsx
<a className={`${styles.siteButton} ${styles.siteButtonRed}`} href="/quote">  Start fitment quote  <ArrowGlyph /></a>
Implementation source

Glass-neumo primitive panel

Use shared panel surface from src/app/ui-primitives/ui-primitives.module.css. This card is the copy contract for agents building the same Mufflermen DNA elsewhere.

Source files

Routesrc/app/ui-primitives/surfaces/page.tsx
Componentsrc/app/ui-primitives/sections/surfaces-section.tsx
Stylessrc/app/ui-primitives/ui-primitives.module.css

Setup

  1. 1
    Use semantic tokens first

    Panel backgrounds, borders, hover shadows and textures must come from primitive tokens so light/dark are intentional profiles.

  2. 2
    Pair glass with structure

    Use 1px borders, compact labels, strong headings and quiet texture so glass does not reduce legibility.

  3. 3
    Reserve glow for state

    Use accent glow for active, risk, ready, needs-review, or live telemetry states only.

Usage guidance

  • Default panels carry content; raised panels call attention to action or status.
  • Use red for urgency, amber for review, teal for system telemetry, green for ready/completed.
  • Do not paste custom dark cards into route modules; alias to the shared surface tokens.

Accessibility notes

  • Text must meet contrast in both profiles.
  • Avoid blur directly behind body copy unless there is a solid panel layer.
  • Motion overlays need `prefers-reduced-motion` support.

Responsive behaviour

  • Panels should use `minmax(0, 1fr)` grids and wrap at existing breakpoints.
  • Avoid fixed-width inner content inside app sections.
  • Use overflow wrapping for codes, VINs, ABNs, part SKUs and route paths.

Required tokens

  • --primitive-panel
  • --primitive-panel-strong
  • --primitive-line
  • --primitive-glass-soft
  • --primitive-neumo-light
  • --primitive-neumo-dark
  • --primitive-shadow-soft

Dependencies

  • CSS Modules
  • primitive layout shell

AI agent notes

  • Light mode should feel like pearl enamel and frosted workshop glass, not inverted dark mode.
  • Dark mode should feel like obsidian, chrome, red paint and instrument glass.
  • Keep the same radius and density across website, Hermes, Pulse, parts and workshop apps.

Panel recipe

CSSsurface-card.module.css
.card {  border: 1px solid var(--primitive-line);  border-radius: 10px;  background:    linear-gradient(180deg, var(--primitive-glass-soft), transparent),    var(--primitive-panel);  box-shadow: var(--primitive-surface-shadow);  backdrop-filter: blur(18px) saturate(1.12);}
Implementation source

KYC primitive appendix pattern

Use PrimitiveImplementationCard from src/app/ui-primitives/components/help-docs. This card is the copy contract for agents building the same Mufflermen DNA elsewhere.

Source files

Routesrc/app/ui-primitives/kyc/id-upload/page.tsx
Componentsrc/app/ui-primitives/components/help-docs/primitive-implementation-card.tsx
Stylessrc/app/ui-primitives/components/help-docs/primitive-implementation-card.module.css
Barrelsrc/app/ui-primitives/components/help-docs/index.ts

Setup

  1. 1
    Keep indexes intact

    Category indexes such as KYC stay as catalogs. Append implementation cards only to primitive detail routes.

  2. 2
    Document the source files

    Every detail route should identify route, component, style, barrel and type files.

  3. 3
    Copy guidance is part of the primitive

    Agent notes must specify domain language, token usage, accessibility and responsive behaviour.

Usage guidance

  • Use this appendix pattern for all primitive detail routes over time.
  • Start with KYC, actions, navigation, surfaces, Hermes, Pulse, parts catalog and marketing heroes.
  • Keep detail docs practical: enough code to recreate the primitive without dumping full source files.

Accessibility notes

  • List required ARIA patterns for each primitive.
  • Call out keyboard/focus expectations.
  • Document reduced-motion and contrast assumptions.

Responsive behaviour

  • State how each primitive collapses on mobile.
  • Document safe minimum widths and wrapping rules.
  • Call out overflow risks for data-heavy primitives.

Required tokens

  • --primitive-font-display
  • --primitive-font-mono
  • --primitive-body
  • --primitive-line
  • --primitive-control-surface

Dependencies

  • CodeBlock
  • PageHeader
  • CSS Modules

AI agent notes

  • Do not replace the existing fuller KYC index.
  • Use route-level docs as source-of-truth contracts for future AI agents.
  • Prefer concise examples over long full-file copies.

Detail route appendix

TSXkyc/id-upload/page.tsx
<PrimitiveImplementationCard doc={KYC_PRIMITIVE_DOCS["id-upload"]} />