# Polanyi Design

> Frontend design cognitive system grounded in Michael Polanyi's tacit knowledge theory. Surfaces expert-level visual judgment in UI design, component architecture, design systems, and aesthetic decisions.

- **Type:** Skill
- **Install:** `agentstack add skill-sunflowerslwtech-polanyi-design-polanyi-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SunflowersLwtech](https://agentstack.voostack.com/s/sunflowerslwtech)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SunflowersLwtech](https://github.com/SunflowersLwtech)
- **Source:** https://github.com/SunflowersLwtech/polanyi-design

## Install

```sh
agentstack add skill-sunflowerslwtech-polanyi-design-polanyi-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Polanyi Design System — Frontend Cognitive Engine

> "We can know more than we can tell." — This skill operationalizes the visual judgment
> that separates a design director's feedback from a bootcamp grad's.

## How This Works

Three systems are available. Match depth to the question — a quick color opinion
doesn't need all five lenses; a full design system review does. Let the problem's
complexity pull you deeper, not a fixed sequence.

Do not announce the machinery. Apply it. The reader should experience better design
thinking, not a lecture about epistemology.

---

## System 1: Knowledge Filter

### Skip / Extract / Push

Every piece of design advice exists on a spectrum:

**SKIP (Explicit ~20%)** — Things any tutorial teaches. Don't restate them.
- How flexbox works. What `gap` does. Tailwind class names. Basic color theory.
- If it's in the docs, it's not your value-add. State it in one line or omit.

**EXTRACT (Implicit)** — What senior designers know but haven't written down. **This is
where you spend your tokens.**
- "I always start with the type scale because spacing flows from line-height"
- "A 60/40 split reads as intentional; 50/50 reads as indecisive"
- "If you're using more than 5 type sizes, you don't have a system — you have accidents"
- "The reason this dashboard needs a 64px nav rail, not a 240px sidebar, is that at 10+
  daily visits the user has memorized the icons. Labels become noise."

**PUSH (Tacit ~80%)** — Knowledge that resists articulation. Approximate it through
three diagnostic properties:
- **Embodied:** Would this feel right to navigate with your hands? Does the layout
  create a physical sense of flow? Does the spacing create breathing or suffocation?
- **Holistic:** Can you perceive this as one integrated voice, or is it a collage of
  parts? Does the design tell a single story?
- **Situational:** Does this solution fit THIS brand, THIS audience, THIS use frequency?
  Would the answer change if the context changed?

### What Can AI Actually Help With?

| Knowledge Type | Example | AI Role |
|---------------|---------|---------|
| **Relational tacit** — nobody wrote it down | "We never use shadows on cards in this system" | **Extract it.** Name the unwritten convention. |
| **Somatic tacit** — embodied in perception | "This spacing feels cramped" | **Approximate.** Translate to: content-to-whitespace ratio, rhythm analysis. |
| **Collective tacit** — embedded in community | "This looks like good React" / "This feels Material" | **Surface the standard.** Name what the community expects without a spec. |

### Calibrate to the Asker

- If they ask "what's a good font size?" → they need explicit guidance. Give it, with
  the implicit reason behind it.
- If they ask "why does this feel like a template?" → they already know the surface.
  Go straight to gestalt diagnosis and tacit judgment.
- If they ask "should I break the grid here?" → they understand the rules. Engage at
  the post-critical level — explain the tacit reason behind the rule and whether this
  context warrants breaking it.

### Aesthetic Judgment Encoding

Six patterns for encoding taste that rules cannot capture:

1. **Negation > Assertion.** Ban the defaults (generic fonts as sole typeface, unmodified
   Tailwind shadow-md + rounded-lg everywhere, purple gradient on white, identical spacing).
   You cannot teach "good taste," but you can teach "what is definitely NOT good taste."
2. **Polarization > Compromise.** Commit to an extreme direction. The middle ground is
   where templates live.
3. **Intentionality > Intensity.** One signature visual decision beats five safe ones.
4. **Anti-Convergence.** Each generation must make different specific choices — never
   the same "safe" combinations.
5. **Taxonomy > Rules.** Offer aesthetic directions (editorial, brutalist, organic,
   geometric, retro-futuristic) and let context determine which fits.
6. **Multi-Layer Coherence.** Direction → 5 domains (type, color, motion, space,
   surface) → specific choices → negation layer. All layers must speak the same voice.

---

## System 2: Five Design Lenses

### Lens 1: Gestalt First — The Whole Before the Parts

**This is the primary lens for all design work.** Before examining any individual element,
perceive the whole.

**Five gestalt diagnostics:**

1. **Figure-Ground** — Is there one clear focal point per viewport? If everything is
   "important," nothing is. Test: squint at the page. What survives? That's your figure.
   Everything else is ground.

2. **Rhythm** — Does the spacing follow a pattern the eye can internalize? Inconsistent
   spacing creates subliminal unease. The user can't name it but feels it. Test: measure
   the gaps. If they're 8, 12, 16, 24, 8, 20 — there's no rhythm. Pick a scale and commit.

3. **Continuity** — Does the visual flow guide the eye along a deliberate path? Left-to-right,
   top-to-bottom for LTR languages, with clear entry points and rest stops. Test: trace
   where your eye goes. If it bounces randomly, continuity is broken.

4. **Voice** — Does every element speak the same visual language? Mixed metaphors break the
   gestalt. A rounded-friendly button next to a sharp-serious table header signals two
   different designers (or zero designers). Test: would you describe the whole page with
   one adjective? If you need three, the voice is fragmented.

5. **Density** — Is the information density appropriate for the use case? A dashboard
   checked 10x/day needs high density and zero decoration. A marketing page seen once
   needs generous whitespace and clear hierarchy. There is no universal "good" density —
   only appropriate density.

**The "feels off" diagnostic:**
When something feels wrong but you can't name it, it's almost always a gestalt failure.
Run the five diagnostics above. The issue is relationships between elements, not any
individual element.

**The "looks like a template" diagnostic:**
The gestalt matches a too-familiar pattern. Every decision is the statistical mode of its
category. Fix: find 2-3 structural decisions that create a distinctive gestalt:
- An unusual but consistent spacing rhythm
- A type pairing that creates a unique voice
- A non-standard layout break that gives the page a signature shape
- A color relationship (not just a palette) that creates a unique mood
- A conviction about corners/shadows (go sharp OR go soft — the middle is where templates live)

---

### Lens 2: Subsidiary-Focal — What Disappears in Use

**Principle:** In a well-designed interface, the design system is *subsidiary* — you look
*through* it, not *at* it. The *focal* concern is the user's task and the content.

**Diagnostic questions:**
- Is the user thinking about the interface or about their work?
- Does the grid/spacing/type system serve the content or dominate it?
- Can a new user perceive the hierarchy without studying the layout?
- Do interactive elements communicate their affordance without labels?

**In design systems:**
- Tokens should be subsidiary: `color-primary` is something you think *through* to
  express emphasis, not something you think *about*.
- Components should enable indwelling: a `` component should feel like an
  extension of the designer's intent, not a constraint to work around.
- When the design system starts to feel like a cage, its subsidiary structure has
  become opaque. The fix is usually to add escape hatches, not more rules.

**In code:**
- CSS-in-JS, utility classes, design tokens — these are subsidiary. If the developer
  spends more time fighting the styling system than building the feature, the system
  has failed its subsidiary role.
- A well-designed component API lets developers think *through* the component to their
  feature, not *about* the component's configuration.

---

### Lens 3: Design Token Hierarchy — From Raw to Meaning

**Principle:** Design knowledge is organized in layers. Each layer serves as subsidiary
to the one above. Each has boundary conditions the layer below cannot determine.

```
Raw values (#2563EB, 16px, Inter, 400)
  ↓ cannot determine
Semantic tokens (color-primary, spacing-md, font-body, weight-regular)
  ↓ cannot determine
Component patterns (button-primary, card-elevated, input-default)
  ↓ cannot determine
Compositions (hero-section, pricing-grid, dashboard-layout)
  ↓ cannot determine
User experience (trust, urgency, delight, clarity)
```

**Key insight:** You cannot derive a good button from good tokens alone. The button needs
its own design decisions (padding ratios, icon sizing, text alignment) that emerge at
the component level. Tokens provide *materials*, not *design*.

**Diagnostic:** When a design system feels "soulless despite good tokens," the problem is
usually at the component or composition layer — the layers that require design judgment,
not just consistent values.

---

### Lens 4: Tacit Translation — Feeling to Fix

**Principle:** Expert designers have tacit reactions ("this feels off") that encode years
of pattern recognition. The skill's job is to translate these into actionable fixes
without losing the felt dimension.

**Translation protocol:**
```
Tacit reaction → Structural cause → Specific fix → Why it matters experientially
```

**Common translations:**

| Feeling | Structural Cause | Fix |
|---------|-----------------|-----|
| "It feels cramped" | Content-to-whitespace ratio too high; no rest stops for the eye | Increase section padding by 1.5x; add 24-32px between content blocks |
| "The hierarchy is flat" | Multiple elements compete for primary attention; no size/weight differential | Pick ONE focal element per section, make it 2x larger or bolder than everything else |
| "It looks dated" | Border-radius + shadow + saturation combo matches 2018-2020 patterns | Reduce saturation 20%, replace box-shadows with subtle borders, use spatial hierarchy instead of containers |
| "It's too busy" | Too many competing visual signals; decoration competing with content | Remove one visual dimension (drop shadows OR borders OR background colors — not all three) |
| "It feels generic" | Every choice is the most popular option in its category (Inter + blue-500 + rounded-lg) | Make 2-3 deliberate deviations: unusual font, shifted color, conviction about corners |
| "It lacks personality" | No intentional visual tension; everything is safely conventional | Add one element of surprise: an oversized number, an unexpected color accent, asymmetric layout |
| "It feels inaccessible" | Interactive elements lack visible focus states; contrast below 4.5:1; no keyboard path | Add 2px outline-offset focus ring in primary color; verify contrast ratios; ensure tab order matches visual order |
| "It feels fragile" | No loading states; layout shifts on data arrival; no error/empty states | Add skeleton screens matching content dimensions; use min-height on data containers; design empty states |

---

### Lens 5: Convention Judgment — When to Break Rules

**Principle:** Rules encode collective tacit knowledge. Understand *why* a rule exists
before deciding whether this context warrants breaking it.

**Design rules and their tacit reasons:**

| Rule | Tacit Reason | When to Break |
|------|-------------|---------------|
| "Use an 8px grid" | Consistent rhythm the eye can internalize | Optical alignment needs 2-4px adjustments; the grid is a tool, not a prison |
| "Max 3 fonts" | Font similarity creates gestalt cohesion | Functional differentiation (mono for code, serif for emphasis) strengthens gestalt |
| "Don't use pure black" | #000 on #FFF creates harsh contrast that fatigues | Data-dense UIs (code editors, dashboards) sometimes need maximum contrast |
| "Cards should have shadows" | Elevation signals interactivity and containment | Flat cards with border-only work in dense layouts; shadow becomes noise |
| "Follow Material/Apple guidelines" | Ecosystem consistency reduces learning curve | When your brand IS the product (Stripe, Linear), distinctive design is a feature |
| "Mobile first" | Prevents desktop-assumption bias | Admin dashboards used 95% on desktop can design desktop-first responsibly |

---

### Cross-Cutting: Accessibility & Resilience

These are **subsidiary requirements** woven into every design response, not a separate
checklist.

**Accessibility as subsidiary design:**
- Focus states: 2px outline, offset 2px, high-contrast — structural like having a roof
- Color contrast: WCAG AA (4.5:1 body, 3:1 large text) — verify pairings, don't assume
- Touch targets: 44px minimum mobile. Motion: respect `prefers-reduced-motion`
- Screen readers: sr-only labels for visual-only indicators (color dots, icon-only buttons)

**Resilience as design quality:**
- Every data-dependent component needs a skeleton matching content dimensions
- Every list needs an empty state. Every async operation needs an error state
- Slow network: placeholder dashes (—), not spinners

### Motion & Animation System

Motion communicates state change, guides attention, and creates spatial continuity.
Every animation needs a functional purpose.

**Duration:** micro (100–150ms) → standard (200–300ms) → emphasis (400–500ms) → data
(600–800ms). **Easing:** ease-out for entrances, ease-in for exits, spring for
interactive feedback. Avoid `linear` — it feels mechanical.

**Choreography:** Stagger siblings by 30–50ms. Lead with the focal element. Exits
faster than entrances. Group related elements (shadow + transform animate together).

Always respect `prefers-reduced-motion` — replace spatial motion with opacity crossfade,
never remove state feedback entirely.

### Data Visualization Color System

Charts need a separate color system from UI chrome. UI colors encode interaction;
data colors encode meaning.

- **Categorical:** Max 6 distinguishable hues. Beyond 6, group data or change chart type.
- **Sequential:** Single-hue ramp (light→dark) for heatmaps and density plots.
- **Divergent:** Red ← neutral gray → green for positive/negative splits.
- **Colorblind safety:** Never encode meaning with red/green alone. Pair color with
  shape, pattern, or label. Blue/orange is safe for >99% of people.

### Quality Verification

When recommending a design, suggest verification across three dimensions:

- **Accessibility:** axe-core, 200% zoom, keyboard tab order, screen reader, vision
  deficiency emulation
- **Visual regression:** Snapshot at 375/768/1440px with real content and slow network
- **Component audit:** Focus states, loading/success/error states, empty states,
  min 12px text, 44px mobile touch targets

---

## System 3: Output Protocol

### Suggested shapes (adapt to context, not rigid templates)

**Diagnosis** ("why does this feel off?"):
Gestalt diagnosis (1 sentence) → specific fixes with values → what NOT to do

**Creation** ("design X for me"):
Design thesis → layout spec → key decisions with tacit rationale → what was excluded

**Component/System work**:
Design principle (what users think THROUGH) → spec → usage example → boundary

### Output Principles

1. **Spec alongside insight.** Pair every design judgment with a concrete value.
   "The hierarchy is flat" → "Set h1 to 48px/600/-0.025em, body to 16px/400.
   The 3:1 size ratio creates clear separation." Insight without implementation
   is a lecture.

2. **Gestalt before pixels.** Diagnose the whole before examining parts. Ten spacing
   nitpicks that miss a broken hierarchy is worse than useless.

3. **Operate at the tacit layer.** If it's in the docs, it's not your value-add. Spend
   tokens on what senior designers know but haven't written down.

4. **Preserve the felt dimension.** When translating "feels off" to fixes, maintain the
   experiential connection — WHY it matters to the person using the interface.

5. **Specify what NOT to do.** Preventing the most likely wrong fix is often more valuable
   than prescribing the right one.

6. **Report everything, grouped by severity.** Gestalt → component → pixel. Never drop
   findings for elegance.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SunflowersLwtech](https://github.com/SunflowersLwtech)
- **Source:** [SunflowersLwtech/polanyi-design](https://github.com/SunflowersLwtech/polanyi-design)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sunflowerslwtech-polanyi-design-polanyi-design
- Seller: https://agentstack.voostack.com/s/sunflowerslwtech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.