Portable instruction packages
Small folders that tell an assistant how to read a design file, what rules apply, and what output shape to produce.
Packet page
The Short Version
This is how I turn design examples and workflow decisions into reusable AI-readable systems.
What I Build
Structured retrieval systems
Searchable stores of examples, notes, specs, records, and relationships that can be found by name, tag, or similarity.
Artifact pipelines
Repeatable paths that turn source material into HTML, mockups, reports, packages, or code and then check the result.
Why This Matters
AI assistants are good at generating plausible design and code. They are bad at reliably generating the same design twice unless the decisions are stored somewhere concrete.
The system stores the decisions outside chat: screenshots for diagnosis, .fig files for structure, skill.md files for instructions, examples for target shapes, scripts for repeatable generation, and databases for retrieval.
A Useful Translation
| Human library term | AI-readable equivalent | What it lets the assistant do |
|---|---|---|
| Visual reference | Screenshot, .fig file, annotated HTML | See the intended layout, structure, and interaction pattern |
| Component guideline | skill.md plus token and spacing references | Build the same pattern with the same constraints |
| Design review note | Validator rule, checklist, or shell script | Catch drift before the artifact is shared |
| Growing library | Structured retrieval system | Find the right example without re-uploading everything |
Reference Point
- Hardik Pandya, Expose your design system to LLMs: The article that frames the shared problem: AI needs specs, tokens, and audits instead of one-time style guidance.
Packet page
The Reusable Stack
The system is organized in layers. Each layer solves a problem the previous layer cannot solve by itself.
Five Layers
| Layer | What lives there | Problem it solves |
|---|---|---|
| Visual Reference | Screenshots, .fig files, annotated HTML pages | Shows what the design should look like or how it is structured |
| Instructional Layer | skill.md, reference files, tokens, spacing rules, scripts | Tells the assistant how to think before it generates |
| Example Layer | Known-good templates, rendered HTML, component records | Gives the assistant a concrete target shape |
| Callable Tool Layer | Shell scripts, bash commands, Python validators, renderers | Makes generation and review repeatable |
| Structured Store | SQL, JSON, indexes, vector search, schemas, Obsidian links | Retrieves the right material when the library gets too large for one session |
How The Layers Build
1. Visual Reference
This layer starts with what can be seen. Screenshots diagnose bugs or capture inspiration. .fig files go deeper: they carry component structure, naming, spacing, relationships, prototypes, and assets.
2. Instructional Layer
This layer tells the assistant how to read the source. It includes skill.md, token lists, color names with hex codes, spacing rules, naming conventions, and scripts that load the right files.
3. Example Layer
This layer stores known-good outputs as code or structured files. The assistant can read the end state directly instead of translating from a vague description.
4. Callable Tool Layer
This layer checks the work. Scripts, renderers, and validators return specific fixes: a missing state, a raw hex value, a broken field, or an output that does not match the expected shape.
5. Structured Store
This layer registers the pieces so they can be retrieved later. SQL tables, JSON records, search indexes, schemas, vector search, local folders, and Obsidian keep the library navigable.
The Human-Facing Layer
A parallel layer runs beside all five: local file organization and Obsidian. That is the browsable surface for people. The machine-facing layer stores the same decisions in files, records, examples, and checks the assistant can use directly.
Packet page
What Each Layer Contains
This is the same stack from the inside: the actual files and folders that make it work.
File Map
| Layer | Files | What they do |
|---|---|---|
| Visual Reference | design.fig, screenshot.png, annotated-page.html | Preserve the visible design, the component tree, and the reference state |
| Instructional Layer | skill.md, references/colors.md, references/spacing.md | Describe how the assistant should read, name, space, and style the work |
| Example Layer | examples/example.html, examples/component.yaml | Show the finished shape in a format the assistant can inspect |
| Callable Tool Layer | scripts/render.sh, scripts/check_tokens.py | Run repeatable generation and drift checks |
| Structured Store | records.json, design_examples.sql, schema.json | Register examples so they can be searched and reused |
A Portable Package
design.fig
The source of visual truth. The assistant reads frames, components, layout relationships, spacing, naming conventions, and linked assets.
skill.md
The primary instruction file. It explains what the package is for, what to inspect first, and which reference files to load when needed.
references/
The supporting memory: colors, tokens, spacing rules, naming conventions, accessibility notes, and common parsing problems.
scripts/
The repeatable operations. A shell or bash script loads the inputs, runs generation, renders output, or checks whether a rule drifted.
Small Package, Large System
A portable instruction package is small and readable: one skill.md plus optional references, scripts, assets, and examples. When the knowledge base gets large enough to need search, tags, schemas, and reliable retrieval, it becomes a structured retrieval system.
Packet page
Concrete Examples
These are the kinds of files that sit behind the workflow. Each one solves a specific reliability problem.
Skill Package
This folder keeps the root readable while references, examples, and scripts carry the working memory.
TEXT
filter-library-skill/
skill.md
README.md
references/
filter-library.fig
colors.md
spacing.md
figma-parsing-notes.md
examples/
filter-toolbar.html
selected-chip.yaml
scripts/
render.sh
check_tokens.pyskill.md Entry
The primary instruction file gives the assistant a reliable reading order before it starts generating UI.
MARKDOWN
# Filter UI Package
Use this package when building or reviewing compact filter controls.
Start by reading:
- references/filter-library.fig
- references/colors.md
- references/spacing.md
- references/figma-parsing-notes.md
- examples/filter-toolbar.html
When generating:
- match the component names and layout relationships in the .fig file
- keep token names unchanged
- include default, hover, focus, selected, and disabled states
- use the example HTML as the output shape, not as decoration
Before sharing:
- run scripts/render.sh
- run scripts/check_tokens.py build/filter-toolbar.htmlColor Token List
A color list pairs plain-language meaning with hex values so the assistant uses the right color for the right job.
MARKDOWN
# Color Tokens
Action blue: #2563EB
Use for primary actions, active chips, and selected controls.
Surface white: #FFFFFF
Use for cards, menus, and editable panels.
Quiet border: #CBD5E1
Use for dividers, chip outlines, and inactive controls.
Warning coral: #F97316
Use only for recoverable warnings or attention states.Spacing Rules
Spacing rules prevent the assistant from inventing a new rhythm every time it lays out the same pattern.
MARKDOWN
# Spacing Rules
4px: icon-to-label gap
8px: chip padding and small control gaps
12px: toolbar item gap
16px: card internal padding
24px: section gap
Do not create new spacing values unless the target layout requires a new scale step.Shell Script
A short shell script makes the same generation path run the same way each time.
BASH
#!/usr/bin/env bash
set -euo pipefail
python scripts/build_component.py \
--source references/filter-library.fig \
--tokens references/colors.md \
--spacing references/spacing.md \
--example examples/filter-toolbar.html \
--out build/filter-toolbar.htmlPython Validator
This validator catches raw color values in rendered HTML where named tokens should be used instead.
PYTHON
from pathlib import Path
import re
import sys
html = Path(sys.argv[1]).read_text()
raw_hex_values = sorted(set(re.findall(r"#[0-9A-Fa-f]{6}", html)))
if raw_hex_values:
print("Use named tokens instead of raw hex values:")
for value in raw_hex_values:
print(f"- {value}")
raise SystemExit(1)JSON Record
A structured record lets a growing library retrieve the right component by name, tags, states, or source.
JSON
{
"id": "component.filter-chip",
"type": "component",
"name": "Filter chip",
"source": "references/filter-library.fig",
"tokens": ["action-blue", "surface-white", "quiet-border"],
"states": ["default", "hover", "focus", "selected", "disabled"],
"examples": ["examples/filter-toolbar.html"],
"retrieval_tags": ["filters", "chips", "compact-controls"]
}Component Spec Record
The component spec stores anatomy and states in a compact form the assistant can reuse directly.
YAML
component: FilterChip
status: reusable
purpose: Narrow a result set without leaving the current surface.
source: references/filter-library.fig
anatomy:
- label
- selected state
- remove icon when active
states:
- default
- hover
- focus
- selected
- disabled
examples:
- examples/filter-toolbar.htmlOutput Bundle
| File | Why it exists |
|---|---|
| skill.md | Primary instructions for reading and using the package |
| README.md | Human-facing summary of what the package contains |
| references/filter-library.fig | Visual structure, components, spacing, and naming |
| references/colors.md | Semantic names plus hex values |
| scripts/render.sh | Repeatable generation path |
| scripts/check_tokens.py | Token drift check |
| examples/filter-toolbar.html | Known-good output the assistant can inspect |
| records/filter-chip.json | Searchable registration when the library grows |
Packet page
How This Maps To Your Element Library
Your visual library is the human-facing start. The system adds the files that make each saved element reusable by an assistant.
From Visual Library To AI Library
| Your library stores | The system adds | Result |
|---|---|---|
| Screenshot | A note that says whether it is for diagnosis or inspiration | The image becomes a decision point, not a fragile source of truth |
| .fig file | skill.md, token references, examples, and parsing notes beside it | The file becomes a portable component package |
| Favorite interaction pattern | States, triggers, feedback rules, and accessibility notes | The assistant can rebuild the flow, not just copy the look |
| Growing set of examples | SQL or JSON records with tags, source links, and reusable parts | The library becomes searchable instead of memory-bound |
What Stays Human
Taste
You still decide what is worth saving, what feels good, and what belongs in the library.
Intent
You decide whether an example is inspiration, a reusable pattern, a debugging reference, or a finished standard.
Judgment
You decide whether the generated artifact actually matches the original design intent after the checks pass.
What Becomes Machine-Readable
Rules
Tokens, spacing, layout rules, naming conventions, states, and component anatomy.
Examples
.fig files, HTML renders, component records, and known-good samples that show the target shape.
Checks
Shell scripts, bash commands, and validators that say exactly what drifted or what is missing.
Packet page
What I Want Your Take On
I am curious whether this maps to how you already collect elements, where it feels useful, and where it gets too heavy.
Three Questions
Does this make sense as a system?
Where did the layers click for you, and where did the explanation get fuzzy?
What would you actually try first?
If you used this with one saved element, what feels worth doing, and what feels like too much overhead?
What already maps to your practice?
Is there something you already do that fits one of these layers: reference, rule, example, check, or searchable record?
Send Me The Rough Take
If any of this sparked a thought about your own system, a question about how it works, or something that did not land, I would love to hear it.
Article
- Expose your design system to LLMs: The clearest framing I have seen for specs, token layers, and audit scripts as AI-facing design-system infrastructure.