Design Tokens: Manual Setup and AI Workflow  🔗 **Source:** [Design Tokens: Manual Setup and AI Workflow](https://www.youtube.com/watch?v=8_NfuJsWDNk) > [!note]+ Document Notes > tags: [design-tokens, penpot, design-systems, ai-workflow, design-engineering] > author: [MISSING] > source: Penpot (YouTube) > reference: https://www.youtube.com/watch?v=8_NfuJsWDNk > date created: 2026-06-29 09:00 > > # 🏷️ Title: Design tokens: manual setup and AI workflow > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - [Penpot design tokens documentation](https://help.penpot.app/user-guide/tokens/) - [Penpot MCP / plugins API](https://penpot.app/) - [Design Tokens Community Group format](https://tr.designtokens.org/) ## 📝 Summary - A short Penpot tutorial shows how to set up design tokens manually, organize them into sets, apply them, and then accelerate the same work with an AI agent through Penpot's MCP. - It matters because hard-coded colors, ad-hoc spacing, and inconsistent styles are the usual failure mode of design files; tokens make those values systematic and referenceable. - Stakeholders: designers and design engineers using Penpot, plus teams adopting token-driven workflows. - Tradeoffs: manual setup is precise but slow; the AI path is fast but depends on the agent reading Penpot's plugins API correctly and inferring sensible naming. - Bottom line: tokens give one source of truth for visual decisions, and an agent can both create and apply them when the tool exposes its API. ## 📖 Main Content - **Sets as collections.** Penpot groups tokens into sets (e.g., `global`, `semantic`), treated like collections for colors, spacing, and typography. Create a set, then create tokens inside it. - **Raw vs. referenced.** Global tokens hold raw values (a hex accent named `color-base-accent`); semantic tokens *reference* globals, so styling resolves through the global layer. Math operations on values are supported. - **Applying.** Apply a token (e.g., border-radius to all corners) from the token tab or properties panel; values update in one place. Composite tokens (shadows, typography) are built from other tokens — typography = font family + size + weight, etc. — and named styles (H1, body-small) apply from the token tab. - **AI acceleration.** The Penpot MCP takes a designed-but-untokenized file, extracts/infers tokens, names them, and rebuilds the same structure (global raw + semantic referencing + composite typography). It applies them directly because it reads Penpot's exposed plugins API. - *Uncertainty:* auto-captions garble names ("pimpot," "pmpotent CP," "penotes" = Penpot / Penpot MCP). No metrics, model name, or accuracy claims for the AI extraction. ### 🗒️ Notes #### ⏱️ [00:00](https://www.youtube.com/watch?v=8_NfuJsWDNk&t=0) Problem and sets - Pain: hard-coded colors, random spacing, inconsistent styles. - Two sets: `global` (token types) and `semantic`; sets act like collections (colors, spacing, typography). Example: accent hex named `color-base-accent`. #### ⏱️ [01:15](https://www.youtube.com/watch?v=8_NfuJsWDNk&t=75) Referencing, math, applying - Semantic tokens reference global because globals are set first; math operations on values are possible. - Apply (e.g., border-radius to all corners) from token tab or properties panel. Composite tokens — shadows, typography (font family + size + weight) — and named styles (H1, body-small) apply from the token tab. #### ⏱️ [02:30](https://www.youtube.com/watch?v=8_NfuJsWDNk&t=150) AI workflow via Penpot MCP - Feed a designed-but-untokenized file; agent extracts/infers tokens, names them, rebuilds global + semantic + typography, and applies them directly by reading Penpot's plugins API. ## 📚 References - [Penpot tokens — official help](https://help.penpot.app/user-guide/tokens/) - [Penpot](https://penpot.app/) - [Design Tokens Format Module (DTCG)](https://tr.designtokens.org/) ## 🗣️ Paraphrase - The first half teaches the manual model: tokens live in named sets that act as collections; global tokens carry raw values and semantic tokens point back at them, so you style through a reference chain and can even compute values. - The second half swaps hand-work for an agent: point Penpot's MCP at an untokenized but fully designed file, and it infers the tokens, names them, rebuilds the same global/semantic/typography structure, and applies them in place because it can read Penpot's plugins API. ## 📰 Newsletter - **Tokens, the easy way (and the AI way).** If your design file is a museum of hard-coded hex values, this 3-minute Penpot walkthrough is worth a watch. It shows the manual path — sets as collections, global raw tokens, semantic tokens that reference them, plus composite shadow/typography tokens — then hands the same job to Penpot's MCP, which infers and applies tokens for you. - **WordPress angle:** this is the same mental model as `theme.json` — global palette/spacing/typography presets that blocks reference by slug rather than raw values. If you think in design tokens, the jump to a token-driven `theme.json` (and to syncing Penpot tokens into a block theme) gets a lot shorter. - Helpful links: [Penpot tokens docs](https://help.penpot.app/user-guide/tokens/) · [DTCG token format](https://tr.designtokens.org/). ## ✅ Action Items #### DevRel - Developer advocacy: record a short companion demo mapping Penpot token sets to WordPress `theme.json` presets. - Education: add a "tokens 101" segment (sets → global → semantic → composite) to a design-systems workshop. - Developer experience: draft a quickstart for the Penpot MCP token-extraction flow with a sample untokenized file. #### WordPress - Design: pilot exporting Penpot semantic tokens into `theme.json` palette/spacing/typography presets; document the naming-convention mapping. - Training: build a lesson on referenced vs. raw tokens using the global/semantic split shown here. #### OSPO - Not applicable to this source — short procedural tutorial with no governance, licensing, or policy content. #### Community - Not applicable to this source — no maintainer/contributor/sponsor content. #### The WPCC - Not applicable to this source — no funding or fellowship content. ### FAIR - Not applicable to this source — no metadata/provenance/governance content. ## 🧪 Hypotheses - AI-inferred token sets that reference a global layer will reduce duplicate raw values in a design file versus manual setup under time pressure. - Files where the tool exposes a complete plugins API will yield higher agent token-application accuracy than files behind opaque APIs. - A semantic-over-global token structure transfers to `theme.json` with fewer remapping steps than a flat token list. - Naming conventions inferred by the agent will need human correction in a measurable fraction of tokens (testable error rate). ## 📊 Methodology - Run a controlled A/B: same untokenized file, manual tokenization vs. Penpot MCP, measure time-to-complete and count of orphaned raw values. - Inter-rater check on inferred token names against a style guide to estimate correction rate. - Round-trip test: export semantic tokens to `theme.json`, render blocks, and diff visual output against the Penpot source. ## ❓ Questions - Which model/agent backs the Penpot MCP, and how is token naming inferred? - How does it decide the global/semantic split and detect composite (shadow/typography) tokens? - Can the agent export to the DTCG JSON format for downstream tools? - What happens on conflicting or near-duplicate raw values during inference? ## 🔮 Future Research - Penpot-token → `theme.json` synchronization pipelines for WordPress block themes. - Accuracy benchmarks for AI token extraction across messy, real-world files. - Bidirectional sync: edits in code flowing back into Penpot token sets. ## 💡 Implications - **Practice:** lowers the activation cost of adopting tokens, so smaller teams can systematize visual decisions. - **Education:** the referenced-token model is teachable in minutes and maps cleanly onto existing design-system curricula. - **Tooling/standards:** value of a tool depends on exposing a readable API; agents are only as good as the surface they can read. - **WordPress:** strengthens the case for token-first `theme.json` authoring. ### 🧠 Learning Styles Assessment - Reading level estimate: Flesch-Kincaid Grade ~9–10 (conversational tutorial narration; short clauses, light jargon). Flesch Reading Ease ~60. #### 👀 Visual learners - Present: screen recording of the token panels, sets, and live application. - Improve: add a before/after diagram and an annotated global→semantic reference arrow. #### 🔊 Aural learners - Present: spoken narration throughout. - Improve: provide a clean 2-minute audio recap without screen-dependent deixis ("here," "this"). #### 🗣️ Verbal learners - Present: terms named in context (sets, global, semantic, composite tokens). - Improve: a short glossary defining raw vs. referenced vs. composite tokens. #### 🧩 Kinesthetic learners - Present: implicit step-by-step you can follow in Penpot. - Improve: a downloadable starter file plus a checklist to reproduce the manual setup. #### 🧠 Logical learners - Present: clear dependency chain (global → semantic → applied element). - Improve: a decision tree for when to use manual vs. AI tokenization. #### 🧑‍🤝‍🧑 Social learners - Present: none. - Improve: a community challenge to tokenize a shared file and compare results. #### 🧘‍♀️ Solitary learners - Present: self-paced video. - Improve: a self-check quiz on token referencing. #### 🌿 Naturalistic learners - Not applicable to this source — short procedural tutorial with no environmental framing. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: spoken narration aids comprehension. - Improve: ensure the published page has proper headings and a descriptive video title/summary. #### Keyboard navigation - Not applicable to this source — it documents a UI workflow rather than providing one to navigate; relevant only to Penpot's own UI. #### Contrast and readability - Present: high-contrast token panels in the recording. - Improve: confirm UI demo text meets 4.5:1 when re-encoded/compressed. #### Text resizing and reflow - Not applicable to this source — fixed video frame; reflow is the host page's responsibility. #### Media and captions - Present: auto-captions (with errors — "pimpot," "penotes"). - Improve: human-corrected captions and a downloadable transcript; no autoplay. #### Forms and interactions - Not applicable to this source — no forms or interactive controls in the artifact. #### Standards reference - Maps to WCAG 2.2 AA: 1.2.2 Captions (correct the auto-captions), 1.2.5 Audio Description (narration relies on "here/this" — add description), 1.4.3 Contrast (verify on re-encode). ### 🌍 DEIB Assessment #### Cultural breadth - Present: tool-agnostic to region; Penpot is open source and self-hostable. - Improve: note multilingual UI availability and localized docs. #### Inclusive language - Present: neutral, task-focused language. - Improve: expand jargon (token, set, composite) for newcomers. #### Neurodiversity support - Present: short, chunked, single-topic flow. - Improve: consistent on-screen labels and a written outline to reduce reliance on spoken deixis. #### Representation - Not applicable to this source — no people or identity content beyond a narrator. #### Psychological safety - Present: encouraging, non-judgmental "today we fix that" framing. - Improve: none needed. ### ✅ Logical Validity #### Strong reasoning - Causal: "semantic tokens can reference global because globals are set first" — a sound dependency-ordering claim; clarify by stating that referencing requires the referent to resolve. - Analogical: "think of [sets] as collections" — a helpful, accurate analogy for grouping. - Inductive: the AI section generalizes from one successful run; strong as a demo, weak as evidence of reliability. #### Fallacies - Mild hasty generalization: "agent can read perfectly the plugins API" implies flawless results from a single demonstrated case. Fix: present accuracy caveats or show an edge case. #### Tone of voice - Instructional, brisk, encouraging ("let's speed things up," "so let's go"). Confident and promotional toward Penpot's AI capability. ### 🛡️ DARVO Analysis - Not applicable to this source — instructional tutorial with no accusation, defense, or conflict dynamics. ## 🎯 Conclusion - Bottom line: design tokens turn scattered raw values into a referenced system, and Penpot lets you build that system by hand or have its MCP infer, name, and apply it for you — because the agent can read the tool's exposed API. - Next steps for readers: replicate the global/semantic/composite structure on a real file, then test the Penpot MCP on an untokenized file and review the inferred names before trusting them. WordPress readers: map the same structure onto `theme.json` presets. ## 🔄 Refactor Appendix — Design tokens: manual setup and AI workflow > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. ### 📚 Literature Atoms (H3) #### [H1] Design tokens replace hard-coded, inconsistent style values > [!quote] ID:rw_pending > "If your designs are still full of hard-coded colors, random spacing values, and inconsistent styles, today we fix that using design tokens" **Context & use**: - Opening of the video (~00:00). - States the core problem tokens solve; the resonance hook for any tokens explainer. **Tags**: #xref #aphorisms **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H2] Penpot groups tokens into global and semantic sets > [!quote] ID:rw_pending > "Inside pimpot, you can group tokens into sets. As you can see here, I have two sets, global with this token types and semantic." **Context & use**: - ~00:30; "pimpot" is an auto-caption error for Penpot. - Captures the global/semantic two-layer structure that the rest of the workflow depends on. **Tags**: #xref **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H3] Agent applies tokens by reading Penpot's plugins API > [!quote] ID:rw_pending > "the agent is able to apply the tokens as you can see here directly in my design and component because agent can read perfectly the plugins API that penpot is exposing" **Context & use**: - ~02:30, the AI-workflow payoff. - Ties agent capability to API exposure — the transferable principle, not just the Penpot specific. **Tags**: #xref #articleseed **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] An agent's design-editing power is bounded by the tool's exposed API **Claim** (one sentence, Courtney's voice): An AI agent can only manipulate a design system as well as the host tool exposes its state through a readable API. **Evidence pointer**: [[#H3]] **Scope & conditions**: Holds when the tool publishes a complete, structured plugins/MCP API; breaks when the API is partial, undocumented, or hides composite-token internals. **Links**: - [[Design tokens as single source of truth]] — because extends - [[theme.json preset architecture]] — because applies-in WordPress block themes - [[MCP tool design]] — because evidence-for <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Test Penpot MCP on a real untokenized file and log the name-correction rate — https://www.youtube.com/watch?v=8_NfuJsWDNk #fleeting #inbox - [F2] Map global/semantic/composite tokens onto `theme.json` presets — does the reference chain survive export? #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Trial Penpot MCP token extraction on a sample file and review inferred naming — design-systems #things - [ ] Draft a Penpot-tokens → theme.json mapping note for the DevRel workshop — devrel #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Design Tokens Manual Setup and AI Workflow.md|Design Tokens: Manual Setup and AI Workflow by youtube.com]] ## Highlights - If your designs are still full of hard-coded colors, random spacing values, and inconsistent styles, today we fix that using design tokens in penot. How to create them, how to organize them and apply them, and then how to accelerate the work using AI. Inside pimpot, you can group tokens into sets. As you can see here, I have two sets, global with this token types and semantic. Think of this as collections, ([View Highlight](https://read.readwise.io/read/01kw9qkde8ehm5qpfvypk1s5vx)) - Note: The problem design tokens solve: hard-coded colors / random spacing / inconsistent styles → token sets (global + semantic). - Tags: penpot, design-tokens, atom/literature/h1 - my design and component because agent can read perfectly the plugins API that penpot is exposing which shows all the information that is key to understand the whole sign. ([View Highlight](https://read.readwise.io/read/01kw9qkghwhkkh0239rp0yxysh)) - Note: Zettel: an agent's design-editing power is bounded by the tool's exposed plugin API — Penpot's open API is what lets AI apply tokens. - Tags: ai-workflow, design-engineering, atom/zettel/z1 ## Links - [[Zet · Align with Core design tokens]] — existing Permanent captures the cross-system value of referencing shared visual decisions instead of hard-coding them. - [[The Design File as a Programmable Bidirectional Surface for Agents]] — applies-in: Penpot's exposed plugin API lets an agent read and mutate tokenized design state.