visual-design-foundations

visual-design-foundations スキルの概要

visual-design-foundations は何のためのスキルか

visual-design-foundations は、曖昧な UI デザイン要件を、タイポグラフィスケール、カラーシステム、スペーシングトークン、アイコノグラフィのルールといった実践的な基盤を使って、一貫したビジュアルシステムへ整理していくためのスキルです。単にインスピレーションが欲しい場面ではなく、短時間で設計の軸を作りたいときに特に役立ちます。たとえば、design tokens の整備、style guide の立ち上げ、視覚的ヒエラルキーの立て直し、プロダクト向け UI システムの初期設計などに向いています。

向いているユーザーとプロジェクト

この visual-design-foundations skill が特にフィットするのは、次のようなケースです。

• ベースラインとなるデザインシステムを定義したいプロダクトデザイナー
• CSS で design tokens を実装したいフロントエンドエンジニア
• 余白、文字組み、セマンティックカラーを標準化したいチーム
• 再利用可能なルールが必要な AI 支援 UI デザインワークフロー

得意なのは完成度の高い最終モックアップを生み出すことよりも、実装時にブレずに運用できる、説明可能な土台をインターフェースに与えることです。

一般的なプロンプトと何が違うのか

通常の「この UI をもっと良くして」といったプロンプトは、どうしても主観的な提案に寄りがちです。visual-design-foundations は、システムとして考えさせたいときに強みがあります。

• 場当たり的なフォントサイズではなく modular typography scales
• 成り行きの padding 値ではなく 8-point spacing logic
• 単発の hex 指定ではなく semantic color tokens
• 見た目の好みだけでなく accessible hierarchy guidance

同梱されている reference も実装観点の情報がしっかりしており、とくに OKLCH color scales、semantic token layering、ratio-based typography まわりは実務で使いやすい内容です。

導入前に多くの人が気にするポイント

visual-design-foundations を入れる前に、多くのユーザーがまず確認したいのは次の点です。

1. 出力が再利用できる token なのか、単なる助言止まりなのか
2. accessibility や dark mode にどこまで対応しやすいか
3. 専任の design system チームがなくても UI 整理の指針になるか
4. サンプルが frontend 実装につなげられる粒度か

この観点では、かなり実務寄りです。ソースには具体的な CSS token pattern が含まれており、最初の出力をそのまま信じる前に読んでおく価値のある reference files も揃っています。

visual-design-foundations スキルの使い方

visual-design-foundations のインストール前提

スキルは wshobson/agents リポジトリからインストールします。

npx skills add https://github.com/wshobson/agents --skill visual-design-foundations

upstream のスキル自体には helper scripts が付属していないため、価値を引き出せるかどうかは、どう呼び出すかと、フルのシステム設計を依頼する前に reference docs を読んでいるかに大きく左右されます。

最初に読むべきファイル

visual-design-foundations install の時間を無駄にしたくないなら、次の順で読むのがおすすめです。

1. plugins/ui-design/skills/visual-design-foundations/SKILL.md
2. plugins/ui-design/skills/visual-design-foundations/references/typography-systems.md
3. plugins/ui-design/skills/visual-design-foundations/references/color-systems.md
4. plugins/ui-design/skills/visual-design-foundations/references/spacing-iconography.md

この順番がよい理由:

• SKILL.md で使える範囲を把握できる
• typography と color の reference に、実装へつながる強いシグナルが最も多い
• spacing と iconography は、抽象的な方針を token や component spacing rules に落とし込むのに役立つ

このスキルがうまく機能するために必要な入力

visual-design-foundations usage の質は、与える入力に大きく依存します。エージェントには次の情報を渡してください。

• product type: SaaS dashboard, mobile app, marketing site, admin tool
• platform: web, iOS, Android, cross-platform
• brand tone: clinical, playful, premium, utilitarian
• current constraints: existing brand color, font, component library, accessibility target
• deliverable needed: token set, style guide, audit, hierarchy revision, dark mode system
• implementation format: CSS variables, Tailwind tokens, design spec, Figma-ready naming

ここが抜けると、どうしても「良いデザインとは」といった汎用的な助言に流れやすくなります。

曖昧な要望を強いプロンプトに変える

弱いプロンプト:

• “Use visual-design-foundations for my app.”

より良いプロンプト:

• “Use visual-design-foundations to define a visual system for a B2B analytics dashboard. I need a typography scale, semantic color tokens, spacing tokens, and icon guidelines. Primary users are analysts working long sessions, so readability matters more than visual novelty. Keep existing brand hue near blue, support light and dark themes, and output implementation-ready CSS custom properties plus rationale.”

このほうが優れている理由は、次を明確にしているからです。

• context
• user needs
• constraints
• outputs
• tradeoffs

出力はレイヤーに分けて依頼する

おすすめの進め方は、次の順で結果を依頼することです。

1. visual principles and constraints
2. typography system
3. spacing system
4. color token system
5. iconography rules
6. component-level application examples

この順番はスキルの構造にも沿っており、質の低い一発出しを減らしやすくなります。

reference を使って実装可能な回答に寄せる

reference files を見ると、このスキルが特に扱いやすい範囲が分かります。

• references/typography-systems.md: modular scale ratios, line-height logic, CSS custom properties
• references/color-systems.md: perceptual scales, semantic tokens, OKLCH examples
• references/spacing-iconography.md: 8-point grid, component spacing tokens, icon sizing consistency

これらの pattern を使うよう明示して依頼すると、曖昧な art direction ではなく、再利用しやすい tokens を得られる可能性が高まります。

UI Design 向け visual-design-foundations の強いプロンプト構成

プロンプトは次の形にすると使いやすいです。

• Goal
• Product context
• Visual tone
• Accessibility requirements
• Existing constraints
• Requested output format
• Examples of screens or components to prioritize

例:

• “Apply visual-design-foundations for UI Design to a healthcare patient portal. Keep the UI calm and trustworthy, preserve our teal brand direction, meet WCAG-friendly contrast expectations, and propose a type scale, semantic colors, spacing tokens, and icon sizing rules. Then show how these choices affect form fields, tables, alerts, and navigation.”

visual-design-foundations が特に得意なこと

実際のところ、visual-design-foundations guide の価値が最も高いのは、次のようなニーズがあるときです。

• 初期段階の token system を作りたい
• 一貫性監査の観点が欲しい
• accessibility を踏まえた color structuring をしたい
• 情報量の多い UI の hierarchy を整理したい
• dark mode の出発点を作りたい
• 実装に落とせる CSS variables が欲しい

特に、「なんとなくデザインがバラついている」状態から、「ここまで定義された運用ルールがある」状態へ進めるのに向いています。

物足りなく感じる可能性がある点

このスキルは、完全な UI kit generator ではありません。リポジトリ構成を見る限り、次のものは含まれていません。

• automated validation tools
• component-specific scripts
• design file exports
• screenshot analysis workflows
• deep brand strategy frameworks

そのため、強いビジュアル探索、marketing の art direction、あるいは motion を多用する bespoke なデザインが主目的なら、これ単体では基礎寄りすぎるかもしれません。

初回出力のあとにやる実務フロー

1回目の出力後は、次の流れが実践的です。

1. 自分たちの codebase に合う token names だけを残す
2. color pairings を実際の accessibility target に照らして検証する
3. type scale を実際の table、form、card レイアウトで試す
4. モデルが variant を増やしすぎた場合は token 数を削る
5. 採用した base size、ratio、brand hue を指定して再度リバイスを依頼する

多くの場合、visual-design-foundations usage が本当に production に効いてくるのは、この 2 パス目からです。

visual-design-foundations スキル FAQ

visual-design-foundations は初心者にも向いている？

はい。基本的な UI 用語が分かっていれば十分使えます。このスキルは typography、color、spacing、iconography に構造を与えてくれるので、出力を通じて学びやすいです。ただし初心者でも、contrast、sizing、実装判断はそのまま丸のみせず、必ず妥当性を確認するべきです。

visual-design-foundations はコードを出す？ それとも原則だけ？

両方に対応できますが、強みがあるのは CSS custom properties や token structures のような、実装を意識した例です。CSS variables、semantic token naming、design-system-ready な出力を明示的に求めるほど、結果は安定しやすくなります。

普通の UI デザインプロンプトより良い？

問題が consistency、hierarchy、token design にあるなら、たいていはこちらのほうが有利です。一般的なプロンプトでも見栄えのする提案は出せますが、engineering が実装できる再現可能なシステムが必要なら、visual-design-foundations skill のほうが実用的です。

visual-design-foundations を監査用途に使える？

はい。既存インターフェースの監査にも向いています。たとえば次の観点です。

• inconsistent spacing
• weak type hierarchy
• non-semantic color use
• icon size drift
• poor readability in dense layouts

より精度の高い audit にしたいなら、screenshots か、現在の tokens と components の棚卸しを文章で渡すと効果的です。

dark mode にも役立つ？

はい、直接的というより間接的に役立ちます。color reference には semantic token の考え方と構造化された scale が含まれているため、dark mode を派生させやすくなります。ゼロから完成度の高い dark mode の見た目を作るというより、theme 化しやすい土台を整えるのが得意です。

visual-design-foundations を使わないほうがいいのはどんなとき？

主な目的が次の場合は、visual-design-foundations は見送ったほうがよいです。

• high-fidelity visual exploration
• brand storytelling and creative direction
• advanced motion design
• illustration systems
• design-system の目的がない単発 landing page の polish

こうしたケースでは、より brand や art direction に寄ったワークフローのほうが適しています。

visual-design-foundations スキルを改善する方法

解決策を求める前に制約を渡す

visual-design-foundations の品質を最も大きく押し上げるのは、制約条件です。少なくとも次は指定すると効果的です。

• base font size
• 分かっていれば preferred type scale ratio
• brand hue または既存 palette
• accessibility target
• density preference: compact, balanced, spacious
• component priorities

これにより、モデルが根拠のある tradeoffs を行いやすくなります。

生の値だけでなく semantic tokens を求める

初回出力が弱くなりやすい典型は、raw の hex colors と font sizes で止まってしまうことです。次の3層を求めてください。

• primitive tokens
• semantic tokens
• component usage guidance

例:

• primitive: blue-500
• semantic: color-action-primary
• usage: button background, active nav state, focus ring

この形にすると、visual-design-foundations guide の出力は導入しやすさが大きく上がります。

過剰な type scale を防ぐ

よくある失敗は、単体で見ると美しいものの、実際のプロダクト画面では破綻する大げさな scale です。改善したいなら、エージェントに次を伝えてください。

• body text size range
• smallest acceptable text
• interface が data-dense かどうか
• headings を控えめにしたいかどうか

dashboard や form では、派手な scale より保守的な scale のほうが機能することが多いです。

spacing を実際の component に結びつける

もうひとつよくある見落としは、きれいな token ladder があっても、実際の UI pattern にうまく対応しないことです。次の spacing rules を見せるよう依頼しましょう。

• form fields
• cards
• tables
• modals
• page sections
• button padding

こうすることで、8-point system を理論ではなく、検証可能な設計判断に変えられます。

color 出力をより安全で使いやすくする

visual-design-foundations for UI Design の精度を上げるには、エージェントに次を分けて提案させるのが有効です。

• brand colors
• surface colors
• text colors
• status colors
• interactive states

あわせて、tinted surfaces、disabled states、subtle borders など、どこで contrast risk が高いか説明させてください。「modern colors を出して」とだけ頼むより、信頼できる palette になりやすいです。

token を減らした改訂を 1 回依頼する

初回出力は steps や semantic roles が多すぎることがよくあります。次のような 2 回目のプロンプトは効果的です。

• “Reduce this system to the minimum viable token set for version 1 while preserving accessibility and consistency.”

これにより、チームがスキルの成果を採用しやすくなります。

推奨内容を自分たちの stack と照らし合わせる

Tailwind、CSS variables、あるいは正式な design token pipeline を使っているなら、その構造にマッピングするよう依頼してください。visual-design-foundations install の価値は、抽象論のまま終わらず、実際の implementation path に沿った出力になるほど高まります。

具体的な Before / After タスクで出力を改善する

漠然と visual system 全体を頼むのではなく、特定の画面改善として依頼すると精度が上がります。

• “Here are the current font sizes, spacing values, and colors on our settings page. Use visual-design-foundations to normalize them into a coherent system and explain what changes first.”

このほうが、オープンエンドな system design よりも、鋭く検証しやすい提案を得られます。

反復で foundation と styling を分ける

安定して使いやすい進め方は次のとおりです。

1. first pass: foundations only
2. second pass: map to tokens
3. third pass: apply to components
4. fourth pass: refine tone and brand expression

この流れなら、visual-design-foundations usage の本来の強み、つまり装飾より先にシステム品質を固めることに集中できます。