Skill + template
A consistent design, an architecture that doesn't break silently
A token-based SwiftUI design system and a SwiftData and CloudKit schema that holds up, including the traps you usually find only after hours of debugging. With real excerpts from Quillino and the incident that stalled my sync in production.
- Agent Skills format
- 6 files, all in English
- Deep on SwiftUI, SwiftData, CloudKit
Why I made it
I learned these rules by breaking things
Quillino is my app for people who rent out one or a few properties. Native SwiftUI, data in SwiftData, synced to the user's iCloud with CloudKit. Almost every rule in this pack arrived after a mistake.
- Sync stalled twice in production, because of two different fields missing from the CloudKit schema. No crash, no visible error: writes were rejected and retried forever.
- The second time, the cause wasn't what I thought. My test seed wrote files of a few bytes, and real files travel on a second field the production schema had never seen. Read the full story.
- The sheet header was copied by hand in about 14 places, already drifting in padding and trailing actions. Today it's a single component.
- A secondary text gray measured 3.6:1 on white. That fails WCAG AA. It's now documented as decorative only.
I wrote it all down so I wouldn't repeat these mistakes on the next app. Then I stripped the private details and made it general.
How it works
From download to a token you can trust
Install it
Unzip it. In Claude Code, Cursor, Copilot, Codex or Gemini CLI, install it the way that tool loads skills (folder name has to stay
design-system-architecture), then open your project so it can read your code. In ChatGPT or Gemini, pasteSKILL.mdas instructions.Ask for what you need
Try: “Set up a token-based design system for my SwiftUI app,” or “audit my code for hardcoded colors and font sizes.” It works one step at a time, so you can also ask for just one, like “just Step 2, contrast.”
Ship without the CloudKit trap
Before a release that touches a synced model, ask: “walk me through the CloudKit release checklist.” It catches the missing schema field before your users do.
What's inside
What's in the zip
- SKILL.md
The method your AI follows. Part 1, design system: typography that scales with the user's text size, color and WCAG contrast in light and dark mode, spacing and motion, components, navigation containers, glossary, and concrete searches to audit hardcoded values in SwiftUI, UIKit, Compose and web code. Part 2, architecture: deploying a CloudKit schema safely, the schema seeder, the _ckAsset trap, SwiftData + CloudKit constraints, schemaless backends like Firestore, versioning and fast QA.
- references/worked-example.md
Real excerpts from Quillino's design system (type scale, measured contrast ratios, navigation rules, glossary) and the full story of the CloudKit schema incident.
- references/design-system-doc-template.md
The document your AI fills in, so the rules live in your project and every new screen follows them.
- references/reskin-mapping.md
Bonus. How to plan a re-skin without touching logic: a mapping table with three coverage levels, a component migration order and a regression protocol. It comes from migrating about 30 screens.
- README.md + LICENSE.md
Install guide for skills-enabled tools, chat assistants and use by hand, plus the full license terms.
How to use each file
From download to results
SKILL.md
What it is: the instructions your AI follows. Part 1, design system (Steps 1 to 8). Part 2, data architecture (Steps 9 to 11).
With a coding agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI): install the folder and open your project. The agent can run the audit searches and write the token code. Ask, for example, “set up a token-based design system for my app” or “walk me through the release checklist for my CloudKit model change”. If it doesn't start on its own, ask for the design-system-architecture skill by name.
With ChatGPT or Gemini: paste the whole file into a custom GPT, Project or Gem, and paste the code you want reviewed.
By hand: Part 1 before designing screens, Step 8 for audits, Part 2 before every release that changes a synced model.
Tip: you can do one step at a time, for example “just Step 2, contrast”. Skip Part 2 if your app has no sync.
“Build me a type scale for my SwiftUI app, with a name and a use for each size.”
| Token | Size | Use |
|---|---|---|
headlineLarge | 34pt | Screen title |
labelMedium | 13pt | Status text |
references/worked-example.md
What it is: real excerpts from a production design system and the full CloudKit incident.
How to use it: read Part 1 before building your token tables, and Part 2 before your next CloudKit model change. Replicate the approach (a specific use per token, a documented limit per failing color), not the exact values.
“Why did my CloudKit sync stall after I added a photo field?”
With a small test value (a few bytes),
the service stores the attribute inline
in a single field, and the deploy succeeds.
Real files are large, and above a
threshold the service stores them in a
separate _ckAsset field instead.references/design-system-doc-template.md
What it is: the design system document the method produces.
With AI: “create DESIGN_SYSTEM.md in my project following the template”, then fill it step by step. Keep it in the repository so future screens and future AI sessions follow it.
By hand: copy it into your project and fill each table during the matching step.
Your platform, and the tokens you fixed while going through Part 1.
## Rules that apply everywhere
- No font size, weight or family set by
hand: use a typography token.
- No color value in views: use a color
token.
- Enforced by: [lint rule / test]references/reskin-mapping.md
What it is: bonus. How to plan a re-skin or migration without touching logic.
How to use it: run the audit searches (Step 8), build the mapping table screen by screen, migrate in the listed order and apply the regression protocol to each screen. With a coding agent: “audit my app and build the re-skin mapping table”, then review the table before any code changes.
“Audit my Home screen and tell me what needs to change for the new design system.”
| Element | Component | Coverage |
|---|---|---|
| Home, balance card | SummaryCard | 🟢 |
| Payment row | ListRow + StatusBadge | 🟡 |
README.md and LICENSE.md
README.md: installation for every kind of tool, example requests, where to start and this per-file guide. Start here.
LICENSE.md: use and adapt the files for your own projects, commercial ones included; don't resell or redistribute them.
A taste
From the pack
A token exists to be the single source of truth. If a rule can be bypassed by typing a value by hand, sooner or later someone will.
SKILL.md
| Token | Size | Weight | Use |
|---|---|---|---|
headlineLarge | 34pt | Bold | Screen title, highlighted number |
titleMedium | 17pt | DemiBold | Primary text in a card |
labelMedium | 13pt | Medium | Badges, labels, status text |
labelSmall | 12pt | Medium | Absolute floor, decorative only |
Is it for you
Honest fit
Yes, if
- you're starting a SwiftUI app and want tokens from day one
- you have an app and the design is drifting
- you use SwiftData with CloudKit, or a similar managed backend
Not if
- you want a Figma kit or code to paste: this is method and rules
- you need an up-to-date API reference: check exact thresholds against Apple's current docs
The worked example is real
What I removed, what I kept
None of the competitors I found sell a method backed by a real case you can check. Usually the example is invented to make the method look brilliant.
These excerpts come from Quillino's internal documentation, and Quillino is on the App Store. In the files I removed the product name, technical identifiers and references to real people. Tokens, contrast ratios and incident mechanics are the real ones.
License
- You can use and adapt the files for yourself and your own projects, commercial ones included.
- You can't redistribute, resell or republish them, in full or in substantial parts, or present them as your own product.
A Markdown file can't be protected technically, so I'm trusting you. Full license
Questions
Can I get a refund?
No. The packs are digital products you download instantly, so there are no refunds. If a file is missing, broken or doesn't match the description, write to quillino.support@gmail.com and it will be fixed.
Is there Swift code ready to copy?
No, on purpose. The pack contains method, rules and real cases. You (or your AI, following the skill) write the code in your project, with your own names and tokens.
Do I have to use SwiftUI and CloudKit?
Part 1 on design systems applies to any platform. Part 2 is written around SwiftData and CloudKit, but the principles (immutable production schema, complete seed, explicit versioning) apply to other managed backends too.
My app isn't on iOS. Is it still useful?
Part 1 works on any platform: the skill shows how tokens map to SwiftUI, UIKit, Jetpack Compose and web, with audit searches for each. Part 2 goes deepest on CloudKit, and has a separate section for schemaless backends like Firestore and for your own API.
Which AI do I need?
It loads as a real skill in Claude, Codex, Cursor, Copilot, Gemini CLI and other tools that support SKILL.md, which is handy since you'll use it while coding. In ChatGPT or Gemini you paste it as instructions. Without AI, it reads as a step-by-step guide.