Figma conventions for agents, from Confluence PRISM 840073301 #378

Activity

1. orioltf

   added

   app:unic-archon-dlc

   p1High priorityHigh priority

   wayfinder:researchWayfinder ticket: investigate against primary sourcesWayfinder ticket: investigate against primary sources

   on Aug 14, 2026
2. orioltf

   added a parent issue on Aug 14, 2026

   • wayfinder: unic-archon-dlc is prose, and proven at a Consumer #373
3. orioltf

   marked this as blocking on Aug 14, 2026

   • Land a rendering component on develop, so the client sees the walk's output #379
4. orioltf commented on Aug 14, 2026

   

   orioltf

   on Aug 14, 2026

   Last edited by orioltf

   MemberAuthor

   More actions

   Stale since 2026-08-20. Superseded by the newest "How to start this session" comment below — the newest opener is authoritative (#373 body). Kept for the record.

   How to start this session

   Produces: the Consumer Figma conventions, captured as a Markdown file in DXP-DesignSystem, plus the
   document shape an agent reads them from.

   Research runs in parallel. Fire this and work another ticket in the same sitting.

   1. Run /wayfinder 373 #378. It claims this ticket.
   2. Check Confluence access before dispatching: ~/.unic-confluence.json — the unic-confluence plugin
      owns it, and /unic-spec-review:spec-doctor verifies it.
   3. Invoke /research. Give it the root page and tell it to walk sub-pages recursively, at least
      two levels down:
      https://uniccom.atlassian.net/wiki/spaces/PRISM/pages/840073301/Research+Agentic+AI+Design+Systems
   4. The findings file lands in the Consumer's clone, not in this repo.

   Traps

   • Primary sources only. A convention nobody wrote down is a finding, not a convention — list it
     separately as an open question.
   • Two outputs, not one: the conventions, and the shape that makes them readable by an agent working in
     the repo. The design-system repo has no CONTEXT.md or AGENTS.md yet.
5. orioltf commented on Aug 20, 2026

   

   orioltf

   on Aug 20, 2026

   Last edited by orioltf

   MemberAuthor

   More actions

   How to start this session

   Posted 2026-08-20 at dispatch. Supersedes the 2026-08-14 opener above — it is marked stale in place.

   Produces: two outputs. First, the Consumer Figma conventions as one Markdown findings file in
   the Consumer's clone, each convention citing the Confluence page it came from. Second, a
   proposed document shape an agent working in that repo would read them from. Invoke /research.
   Do not invoke /implement — it routes to /tdd, and decisions 3 and 11 deleted the tests. Never
   run /setup-matt-pocock-skills — the tracker docs it would "restore" already exist and are correct.

   Read order

   1. This ticket's body — the two outputs and the four criteria.
   2. DXP-DesignSystem/docs/agents/issue-tracker.md and triage-labels.md — the only prose that repo
      already keeps for agents. Output 2 must sit beside these, so know their shape before proposing.
   3. Confluence PRISM 840073301 ("Research: Agentic AI Design Systems") and its sub-pages,
      recursively, at least two levels down. This is the source; read it through /research, not by
      skimming the root page.

   The one trap

   The findings file lands in DXP-DesignSystem, never in this repository. The /research Method
   says "save it in the repo", and your working directory is unic-agents-plugins, so the skill's
   default is the wrong repo here. Do the Consumer work in a fresh git worktree of
   DXP-DesignSystem — never in the main clone, which the maintainer also holds open.

   The decision the ticket does not make

   Where in the Consumer the file goes. That repo has only docs/agents/. Decision: put the findings
   at docs/research/ (create the directory — it mirrors this repo's layout), and keep output 2 as a
   proposal inside the findings file. Do not scaffold a CONTEXT.md or AGENTS.md — #377 and
   #379 read the proposal before anything gets built.

   Other traps

   • Confluence credentials are at ~/.unic-confluence.json (verified present 2026-08-20). If a fetch
     fails, run /unic-spec-review:spec-doctor before diagnosing anything else.
   • A convention nobody wrote down is a finding, not a convention. It goes in a separate
     open-questions section (criterion 2). Never state a claim the pages do not make; an unverifiable
     claim is listed separately, not woven in.
   • Consumer git guards: first push is git push -u origin <branch>; before every push run
     git rev-list --count origin/develop..HEAD and stop on a zero or absurd count; develop refuses
     direct pushes (hook plus denied Contribute), so everything goes through a PR.
   • ADO PR descriptions cap at 4000 characters. Detail goes in a thread.

   The bar that proves it

   Every convention row links the page it came from, and the links resolve. A false pass looks
   like: a plausible convention list whose citations all point at the root page — that means the
   recursive walk never happened. A second false pass: the file exists, but in this repository.

   On landing

   1. Open a normal ADO PR (not draft) from the worktree branch to develop.
   2. Self-review: archon workflow run unic-dlc-pr-review "<slug>" --from <branch>. Approve the
      review-gate from the terminal (archon workflow approve <id>) — approving in the UI
      leaves the run paused forever. Never reject: the gate has no on_reject, so a reject
      destroys every finding. If findings look wrong, approve, let them post, answer on the threads.
      Cap: 3 rounds.
   3. Read the run's findings for what they say about the plugin, not only this file, and file any
      plugin defect in this repository.
   4. Before handover, re-read your own PR description and re-verify every claim in it against the
      final diff.
   5. Comment here with the findings-file path and the PR link, and comment on What are the Consumer design system's first slices? #377 that the findings
      are in — its opener reads them first.
   6. No plugin version bump — this ticket ships nothing in the plugin.

   Report back

   BEFORE YOU FINISH, AND WHENEVER YOU LEARN SOMETHING THAT WOULD HAVE CHANGED THIS PROMPT,
   SendMessage to wayfinder-orchestrator with four things and nothing else:

   1. what you expected
   2. what happened
   3. the command or file that proved it
   4. whether it changes only this ticket, or every session in this repo

   Send it when you learn it, not only at the end — a session that dies unreported takes its
   learnings with it.
6. orioltf

   self-assigned this

   on Aug 20, 2026
7. orioltf commented on Aug 23, 2026

   

   orioltf

   on Aug 23, 2026

   Last edited by orioltf

   MemberAuthor

   More actions

   Resolution

   The conventions exist. The ticket pointed at the wrong subtree, and the Figma file has moved past the documentation.

   Findings file: docs/research/figma-conventions-for-agents.md in DXP-DesignSystem, merged on develop as d177e6f via !5783, work item 42953.

   The answer

   PRISM 840073301, which this ticket named, holds no Figma convention. All nineteen pages were read: "Figma" appears once, in a bibliography line on the root page. It is a literature review of one external demo and one external article.

   The conventions are one folder away, in PRISM 852591905 — three pages:

   • Figma Design-to-Code Guidelines (Work in Progress), 3 Jun 2026, current. Token layers, naming rules, Token Studio export limits, component structure, property types, states, spacing frames, animations.
   • Two pages their author moved into a folder named old on 2 Jun, the day before writing the replacement: General Figma Designer Documentation and Component & Variant Naming Convention. The naming page is the only home for four rules the current page dropped — PascalCase names, exact Figma-to-code matching, a description on every component, property names matching code props. Of the ten components on the design system's own pages, one obeys the first.

   Supporting conventions sit in the DXP space: Figma Usage Guidelines and Motion Guidelines, the newest convention document in either space.

   Scope was widened deliberately, and it was the right call

   Reading Confluence alone would have produced a document that is true and useless. The documentation is dated 3 June and the file was last edited 21 August, so the live Figma file was read directly. That produced seven documented-versus-actual disagreements and eight defects in the file, including two misspellings shipped in sibling components (secundary against secondary, larg-ultra against large-ultra) and a scratch page publishing ten components with duplicate names. One defect — a case-duplicate state on card-profile-main — was found and fixed by the designer the same day.

   The finding that changed a working assumption

   get_variable_defs returns resolved token values, across the library boundary, from a node in the design-system file. The Token Studio detour and the join-primitives-in-code step exist to route around a limitation that no longer holds. So the design files are the source of truth for tokens — decided by the maintainer on 2026-08-21, with three conditions recorded beside it: only bound variables resolve, reading one needs edit access rather than view, and there is no whole-palette read.

   Output 2, and why it is not written

   docs/agents/figma.md, beside issue-tracker.md and triage-labels.md, copying their shape. It cannot be written yet, and the blocker is decisions rather than access. The single most important thing only that file can carry: the Figma file keys, because get_libraries returns library keys and nothing resolves a library to a file — an agent cannot find them by looking.

   What this ticket produced besides the note

   Ticket
   #403	how a component represents three or more variant dimensions
   #404	what a component design contract contains, and what /specs writes
   #405	what counts as design intent when a file carries data nobody chose
   #406	edit access to the Global Tokens and Assets files
   #407	plugin defect: the Box rediscovers the ADO inline-thread anchor shape by failing, every run

   Five questions stay unowned because four of the five need the design system's author: the status of the four rules in old, which file numbering is current, whether the (New) trio supersedes the originals, how the two animation conventions reconcile, and the breakpoint pixel values.

   Both directions of the two-repository rule are done

   Plugin → Consumer: nothing to port; this ticket ships no plugin change and no version bump.

   Consumer → plugin: two unic-dlc-pr-review iterations ran against !5783 — 12 findings then 8, with 10 fixed and 0 regressed between them. Two caught factual errors that would have shipped: a component miscount, and a false claim that this repository has no Chromatic (the addon is installed; the project and CI wiring are not). Iteration 2 also caught my iteration-1 fix putting one fact in three homes. The plugin defect that run surfaced is #407.

   Caveats carried into the note rather than hidden

   Two claims are marked unverified and attributed: the instance-override carry-over mechanism, and copy-paste creating library subscriptions. Both come from the maintainer's and the designer's own testing. The DXP Confluence space was sampled, not exhausted — a text ~ "Figma" search caps at 100 results. PRISM was exhausted.
8. orioltf

   closed this as completedon Aug 23, 2026