Working with Visiona — A Practical Guide

You installed the skill. Now what? This is the cheat sheet.

1. Pick Your System (30 seconds)

Open skills/visiona/gallery/index.html in a browser. That's your lookbook — 15 complete design systems, every component rendered.

Here's the personality of each:

• Mat Navy — clean SaaS default. Safe, professional, works everywhere.
• Bone & Ink — editorial serif elegance. Magazines, longform, portfolios.
• Terminal Green — hacker aesthetic. Dev tools, CLIs, monitoring dashboards.
• Cream Stack — warm and approachable. Landing pages, indie products.
• Obsidian — dark luxury with amber accents. Fintech, crypto, premium tools.
• Arctic — cold, precise, minimal. Data platforms, analytics, medical.
• Amber Workshop — industrial warmth. Maker tools, construction, hardware.
• Dusk — muted purple twilight. Creative tools, music, nightlife.
• Slate & Lime — high-contrast neon on dark. Gaming, esports, energy.
• Paper — light mode done right. Documentation, wikis, publishing.
• Coral Bloom — soft coral on dark. Wellness, lifestyle, beauty.
• Bold Editorial — high-impact type-forward. News, opinion, content platforms.
• Ice Blue — cool, clinical, trustworthy. Healthcare, enterprise, compliance.
• Riot Red — aggressive, unapologetic. Martial arts, sports, action brands.
• Soft Carbon — subtle dark neutral. The quiet professional. Works when you want zero personality.

Can't decide? Tell Visiona your product and audience. She'll pick for you.

2. Get Your Tokens (2 minutes)

Every system is a single HTML file in skills/visiona/gallery/. Open any one (e.g., obsidian.html) and find the :root block at the top. That's your token set.

Copy the entire :root { ... } block into your project's CSS. Done.

Token naming convention:

All colors use OKLCH — perceptually uniform, great for dark/light mode math.

Don't memorize the tokens. Just use var(--color-surface-2) for a card background, var(--color-accent) for a button, var(--color-text-muted) for secondary text. The naming is the documentation.

3. Ask Visiona to Build

Best prompts are specific about system + component + context:

"Build a pricing page using the Obsidian system. Three tiers, annual/monthly toggle, dark mode."

"Create a settings sidebar using Arctic tokens. Collapsible sections, avatar at top."

"Pick the best system for a BJJ gym management dashboard, then build the member list table."

Visiona pulls the right tokens and generates production-ready HTML/CSS.

Weak prompts (avoid): "Make it look nice" or "Build me a website." No system, no component, no context = generic output.

4. Ask Visiona to Critique

Send a screenshot, a URL, or paste your code. Then ask something specific:

"What's wrong with this card component? Be brutal."

"This dashboard feels off but I can't say why. Diagnose it."

"Audit this page for contrast issues and typography hierarchy."

Visiona critiques against real principles — spacing, contrast, type scale, visual weight. Not platitudes.

Ask for the critique before the fix. Deeper frameworks: skills/visiona/references/ (23 guides).

5. Customize a System

Safe to change:

• --color-accent (and its hover/tonal/dim variants) — swap your brand color in
• --font-display and --font-body — change typefaces
• --btn-radius, --card-radius — adjust roundness feel

Don't touch unless you know what you're doing:

• --color-bg through --color-surface-5 — these are tuned as a layered elevation system. Change one and the depth breaks.
• --color-text-primary / secondary / muted — contrast ratios are pre-calculated against surfaces. Random changes = WCAG failures.
• The spacing scale — it's consistent across all 15 systems for a reason.

The rule: Swap accent and fonts freely. Touch surfaces and text colors as a coordinated set, not individually.

6. Add a New System

1. Define your tokens in a new .md file in skills/visiona/library/systems/
2. The master template lives at skills/visiona/template/design-system-template.html — it has every component section (Part 1: tokens/foundations, Part 2: components, Part 3: charts)
3. Run the build script: node skills/visiona/scripts/build-gallery.js
4. Your new system appears in the gallery with all 20 component sections rendered

Or just tell Visiona: "Create a new design system called Midnight Ember — dark base, warm orange accents, monospace typography, brutalist radius." She'll generate the token file, build the gallery page, and add it to the index.

7. The Build Loop

This is the workflow that actually works:

Brief → Pick system → Visiona builds → You critique → Visiona fixes → Ship

1. Brief — What you're building, who it's for, what it should feel like
2. Pick — Choose a system or let Visiona recommend
3. Build — Visiona generates the component or page
4. Critique — React honestly. "Spacing feels tight." "Button doesn't pop."
5. Fix — Visiona iterates on your feedback
6. Ship — Done

Don't skip step 4. The best output comes from the loop, not the first pass.

Quick Reference

Visiona Silva — 15 systems, 300 components, zero generic output. Ask for what you want. Be specific. Get something worth shipping.