AFL
SkillsBuild

redesign-afl-widget

The redesign track. Rebuilding a widget from the design system and Figma.

One ticket, one tracker item on the redesign track. The design system is the source of truth, not the live site: there is no pixel parity, no HAR and no legacy scale. For a like-for-like port of the live widget use migrate-afl-widget instead.

Read apps/migration-tracker/content/docs/index.md first then taxonomy.md, pipeline.md and sync-design-tokens.md in the same folder.

Done means: the widget is built in packages/ui from design system primitives and ds- tokens on the default Tailwind scale; the Figma comparison, accessibility and behaviour checks are published to the tracker; the item is reviewed; and a PR is open. A designer moves it to approved in the tracker. You never set approved yourself.

0. Load the item

curl -s "$TRACKER_URL/api/items/<widget-id>"

Stop and say so on the ticket if track is not redesign. Record this run straight away, using the Software Factory job number this run was started with:

curl -s -X PATCH "$TRACKER_URL/api/items/<widget-id>" \
  -H "authorization: Bearer $TRACKER_API_TOKEN" -H "content-type: application/json" \
  -d '{"sfJob": "<job number>", "actor": "software-factory"}'

If the item already has a different sf_job, this is a regeneration. Run this from the repo root, passing the component (a redesign item has widget.design.ts, and rebuild.ts defaults to importing widget.ts): bun run --cwd tools/parity parity:rebuild <widget-id> --component <ui component> --trigger "<why>" --change-log "<what changes>" instead of calling the API by hand: it records the rebuild and snapshots the prior field mappings, latest runs and fixtures. After the build and its checks, parity:publish publishes the rebuild report (fields added, removed or changed, and checks that changed state); summarise it in the PR. Redesign items have no live baseline, so the yellow screenshot threshold only applies to the report's build-to-build screenshot comparison; the figma check never fails on a difference.

The ticket policy is the one in migrate-afl-widget ("Ticket and change-log policy"): the change log is always written, the item's original ticket is reused, and --track files one child ticket under it only for a substantive change.

If mergedFrom lists items, this redesign replaces all of them: load each one, read its legacy audit row in apps/migration-tracker/data/legacy-audit.json and its pages, and build one component that covers every variant they had (usually as props or variants, not copies). Note priority, pages, Pulse widgets and notes.

Branch: claude/<JIRA-KEY>-redesign-<widget-id> from main.

1. Read the design system (reference only)

The design system lives in Two-Circles/telstra-legacy-afl-design-system (a mirror of Pulse's afl-design-system). Read it; never import it, add it as a dependency or copy its build output. Read it at the commit pinned in packages/config/scripts/sync-design-system.ts:

gh api "repos/Two-Circles/telstra-legacy-afl-design-system/contents/lib/components/ui?ref=<commit>"
  • lib/components/ui/atoms and molecules: the React components (shadcn base-luma on Base UI) and their variants. Match their API, states and accessibility.
  • **/*.figma.ts: Code Connect files mapping each component to its Figma node in the AFLDS libraries (figma.config.json: Foundation, Core and Web).
  • lib/css/theme and lib/css/variables: already generated into packages/config/src/design-system.css as ds- tokens.

2. Find the design in Figma

Use the Figma MCP server (it must be authorised for this run). Start a session for the AFLDS-Web-Library file (C1zOyrKrZerjgnGUB9xvFj) and, when the figma-design-to-code skill is available, load it before reading design context.

  1. Find the widget's component in AFLDS-Web-Library (search the design system or the file's metadata by name; the legacy widget names and Pulse names on the item help).
  2. Read its design context and variables, and note every variant: breakpoints, states (hover, focus, pressed), themes and content lengths.
  3. Export a screenshot of the component at each breakpoint variant to tools/parity/widgets/<widget-id>/figma/<viewport>.png, and each interaction state to <viewport>-<behaviour name>.png. Use the viewport the variant is designed for (e.g. 375, 768, 1280).
  4. PATCH the item: designComponent (the component's name), figmaUrl (a link to its node) and status: "designed".

If there is no component for this widget in AFLDS-Web-Library, stop and comment on the ticket with what you searched for. Do not invent a design.

3. Build the component

  1. Read the Optimizely type from Graph (packages/content/src/optimizely/schema.graphql). Never create or change a content type; if a field is missing, stop and comment on the ticket.
  2. Build in packages/ui/src/<component>/ on the default Tailwind scale. Never add the legacy-scale class or rem values that assume a 10px root.
  3. Style only with design system tokens from @afl/config: colours bg-ds-primary, text-ds-on-surface; spacing p-ds-xs, gap-ds-s; radius rounded-ds-sm; shadows shadow-ds-2; type classes ds-title-l-bold, ds-body-m-regular; breakpoints ds-s: to ds-2xl:. Club themes come from data-club-theme="<club>" and AFLM/AFLW/finals from data-theme. If a token is missing or stale, bump the commit in packages/config/scripts/sync-design-system.ts and run bun run --cwd packages/config sync:design-system; never hand-edit design-system.css.
  4. Build missing design system primitives (button, badge, chip, content card and so on) in packages/ui with the same names, variants and ARIA as the design system's React component, shadcn style, so other widgets reuse them. Reuse ones that already exist.
  5. Fixture JSON in packages/ui/src/<component>/fixtures/, a Zod schema, a story using the fixture, and behaviour tests. Wire it through the block registry as in docs/adding-a-block.md. No code comments.
  6. PATCH status: "built".

4. Review

Write tools/parity/widgets/<widget-id>/widget.design.ts:

import { design } from "../../src/design";
import { defineDesign } from "../../src/widget";

design(
  defineDesign({
    id: "<widget-id>",
    component: "<component>",
    fixture: "<fixture>",
    designComponent: "<Figma component name>",
    figmaFile: "C1zOyrKrZerjgnGUB9xvFj",
    frames: [{ viewport: 375, width: 343, node: "<node id>" }],
    behaviours: [{ name: "hover card", action: "hover", selector: "[data-slot=content-card] a" }],
  }),
);

width is the component's width in that Figma frame. Then:

bun run --cwd tools/parity parity -g <widget-id>
  • a11y (axe, WCAG 2.1 AA) and every behaviour must pass. Fix the component, never the check.
  • figma never fails on a difference: it records the share of pixels that differ and both images. Open the report and fix anything that is clearly wrong (spacing, colour, type, missing elements). Content and image differences are expected.

Publish, then PATCH status: "reviewed":

bun run --cwd tools/parity parity:publish

5. Raise the PR

  1. Run the repo checks from AGENTS.md (bun run check, bun run typecheck, bun run test, bun run knip, bun run build).
  2. Open the PR into main using the template: what changed, which design system component and Figma node it follows, which legacy widgets it replaces, the Figma difference scores and anything you chose not to match, and the Jira link. Attach the tracker item URL and ask a designer to approve it there.

migrate-afl-widget

The parity track. The procedure the Software Factory follows to copy a live widget and prove it matches.

create-ticket

Creating a build ticket from a widget spec and recording it in the tracker.

On this page

0. Load the item1. Read the design system (reference only)2. Find the design in Figma3. Build the component4. Review5. Raise the PR