layers-surface
Techniques for auditing and deciding the surface against the layers below — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility
- Installs
- 2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/jamiemill/layers-skills --skill layers-surface- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads layers-surface automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
/layers-surface
Assumes /layers-intro has been loaded. This skill is a library of techniques, not a script — see "How to use these skills" there.
The surface layer is where everything decided below becomes something a person actually encounters: words, sounds, visuals, physical affordances, motion, feedback. It's the most medium-specific layer, but the decisions that matter most first are universal — they hold whether the surface is a screen, voice interface, physical device, or service touchpoint.
Surface problems are often symptoms of deeper ones. The central discipline here is telling apart issues you can fix at the surface from issues that need a lower layer revisited.
The decisions this layer makes
- Whether the surface honours the vocabulary and objects from the conceptual model
- Whether every affordance from the breadboard is present — and whether any surface element has no model behind it
- Whether the emotional register fits the jobs users are doing
- How the user knows what happened, what's in progress, and what went wrong
- What's most prominent, and whether it should be
- Whether everything is accessible to the users who need it
Disciplines — what keeps the surface honest
- Surface fix vs deeper-layer issue. The key judgement: is this something to fix in the copy/layout, or a symptom whose root is in the conceptual model or interaction flow? Wrong vocabulary may be a rewrite — or a model that never settled the term. Route deeper issues back to the relevant skill rather than patching the symptom.
- Terms match the ubiquitous language. Flag direct violations (a model term used inconsistently), unlisted terms (surface words not in the model — add to model, or remove as noise), and tone misalignments.
- Object consistency. No shapeshifters (same object in significantly different forms across contexts), no masked objects (a form where the user can't recognise the object type).
- Completeness both ways. Every breadboard affordance is present; no surface element exists with no model or flow behind it (those are interaction decisions that slipped through — route to
/layers-interaction-flow). - Errors diagnose, explain, recover. "Something went wrong" fails all three. Flag every error state that doesn't do all three.
- Prominence reflects importance. What the flow needs the user to notice is what stands out; nothing prominent that shouldn't be.
- Accessibility is decided, not defaulted.
- Emotional register matches the emotional and social jobs from user needs — not the product's benefit framed as the user's.
Techniques
Two kinds of work live here: auditing existing surface against the layers below, and working through open surface decisions. Use whichever the situation calls for.
| Technique | Use it to |
|---|---|
| Vocabulary check | Take the ubiquitous language list; check every label, heading, button, error, notification, help string against it. |
| Object-consistency check | For each model object: where does it appear, in how many forms? Catch shapeshifters and masked objects. |
| Completeness check | Walk the breadboard against the surface in both directions — missing affordances, and surface with no model behind it. |
| Emotional-register check | Return to the emotional and social jobs; find where tone, framing, or emphasis misaligns. |
| Feedback & error inventory | For each action and state transition: how does the user know it worked, is in progress, or failed — and what to do next? |
| Hierarchy review | Per key place: what must the user notice or act on, and does the surface make that most prominent? Decide what's primary before how to signal it. |
| Accessibility pass | Per medium — screen (contrast, sizing, touch targets, keyboard, screen-reader labels, focus), voice (everything conveyed verbally, recovery without visual context), physical (reach, tactile differentiation, lighting, no fine-motor requirement). |
| Consistency pass | Similar things treated similarly, different things differently; medium conventions honoured or deliberately broken. |
| Make it (real medium, mockups, style tiles, prototypes, design system, copy-first) | When producing surface rather than auditing it. Work in code for real interaction feedback; mockups for layout/hierarchy; style tiles for early tone; prototypes for timing and motion; extend (don't contradict) an existing design system; write copy first when language is the primary material. |
Working with the designer
Establish the medium and what exists from below — conceptual model (objects + ubiquitous language), breadboard, job stories including emotional/social jobs. If surface exists, audit it; if not, work the open decisions.
Offer the technique that fits the live concern — a vocabulary check when terms feel off, a feedback inventory when users don't know what happened, an accessibility pass when it's been left to defaults. Don't run all ten.
Capture only the residue: audit findings (each tagged surface-fix or deeper-layer issue), the open surface decisions grouped and prioritised (with options and constraints), the cross-layer issues to resolve first, and what's already working well so it isn't lost in revision.
The surface either honours what's decided below or undermines it. Revisit after any significant change to the conceptual model or interaction structure.
FAQ
What does the layers-surface skill do?
Techniques for auditing and deciding the surface against the layers below — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility
How do I install layers-surface?
Run npx skills add https://github.com/jamiemill/layers-skills --skill layers-surface in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/layers-surface/ (personal) or .claude/skills/layers-surface/ (project).
Which AI agents can use layers-surface?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is layers-surface safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains layers-surface?
It is published by jamiemill in jamiemill/layers-skills. It has 1,962 recorded installs.
More from jamiemill/layers-skills
layers-conceptual-model
jamiemill/layers-skills
Techniques for defining the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer
layers-intro
jamiemill/layers-skills
Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on
layers-interaction-flow
jamiemill/layers-skills
Techniques for mapping interaction structure and flow — places, affordances, edge cases, and failure paths — without committing to visual form
layers-product-strategy
jamiemill/layers-skills
Techniques for connecting user opportunities to business outcomes and solution bets, and testing the riskiest assumptions cheaply
layers-orient
jamiemill/layers-skills
Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus
layers-domain
jamiemill/layers-skills
Techniques for mapping a domain's concepts, terminology conflicts, and bounded contexts — the raw material the conceptual model is built from
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.