@skill-graph/cli 0.5.6

package/marketplace/skills/semantics/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: semantics
+description: "Use when naming artifacts across code, APIs, design tokens, commits, HTTP/status signals, UI labels, error codes, or branded types, especially when a name feels ambiguous or misleading. Covers cross-domain meaning-encoding: naming smells, DDD ubiquitous language, SemVer, conventional commits, branded types, semantic design tokens/CSS/APIs, semantic UI affordances, and naming anti-patterns. Do NOT use for word morphology/polysemy (use linguistics), casing formats (use naming-conventions), typed concept relations (use semantic-relations), or in-product UI-text patterns (use microcopy)."
+license: MIT
+compatibility: "Cross-domain naming and meaning skill, stack-agnostic. The naming-smells catalogue, SemVer rules, conventional-commit format, three-layer token architecture, HTTP-status semantics, REST/GraphQL conventions, and anti-pattern catalog apply to any codebase; example identifiers use generic e-commerce framings — substitute the equivalents from your domain."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.1.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/semantics\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"semantic naming\\\\\\\",\\\\\\\"semantic drift detection\\\\\\\",\\\\\\\"branded type design\\\\\\\",\\\\\\\"semantic versioning rules\\\\\\\",\\\\\\\"conventional commit type choice\\\\\\\",\\\\\\\"HTTP status semantic signaling\\\\\\\",\\\\\\\"design-token semantic layer\\\\\\\",\\\\\\\"naming smells catalogue\\\\\\\",\\\\\\\"DDD ubiquitous language\\\\\\\",\\\\\\\"semantic affordance naming\\\\\\\",\\\\\\\"semantic UI signal\\\\\\\",\\\\\\\"semantic API contract\\\\\\\",\\\\\\\"parse-do-not-validate pattern\\\\\\\",\\\\\\\"three-layer token architecture\\\\\\\",\\\\\\\"meaning-encoding identifier\\\\\\\",\\\\\\\"semantic-vs-syntactic distinction\\\\\\\",\\\\\\\"cargo-cult naming anti-pattern\\\\\\\"]\",\"examples\":\"[\\\\\\\"a function named process(data) actually reconciles revenue with production cost — what semantic rename would make the operation self-explanatory without reading the implementation?\\\\\\\",\\\\\\\"our API returns HTTP 200 with { success: false, error: 'User not found' } — is that syntactically valid but semantically wrong, and what should the response signal be instead?\\\\\\\",\\\\\\\"we named a token --light-blue and now dark mode plus rebranding broke its meaning — what semantic token pattern should replace it?\\\\\\\",\\\\\\\"a variable called provider could mean payment, fulfillment, or auth in three different modules — how should semantics resolve that ambiguity?\\\\\\\",\\\\\\\"I need to choose between feat(billing): add email notifications and chore(billing): add email notifications — which commit message is semantically correct?\\\\\\\",\\\\\\\"should this ID be a branded type or a plain string, and what does parse-don't-validate mean for it?\\\\\\\",\\\\\\\"audit this database schema for unitless financial columns and timestamp-naming drift\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"should onboarding be hyphenated, and how does English compound morphology affect that decision?\\\\\\\",\\\\\\\"what does margin mean in finance reporting versus CSS layout — give me the canonical definition?\\\\\\\",\\\\\\\"what casing should a new database timestamp column use — kebab, snake, or camel?\\\\\\\",\\\\\\\"audit whether this button has the correct aria-label and focus semantics for screen readers\\\\\\\",\\\\\\\"decide whether these entities should live in a strict hierarchy or a faceted taxonomy\\\\\\\",\\\\\\\"draft the empty-state copy for a freshly connected storefront with no orders yet\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"linguistics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"linguistics owns word-form rules (morphology, compound-word ordering, abbreviation policy, audience register, blame-free phrasing); semantics owns meaning encoding (what the name communicates, semantic drift, branded types, HTTP-status semantics, SemVer signaling) — the same 'is this name good?' prompt routes by whether the trigger is the form of the word or the meaning the name encodes\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"naming-conventions owns the deterministic casing/format choice per artifact kind (kebab vs camel vs snake vs Pascal); semantics owns the meaning encoding behind the name — the same 'what should I call this?' prompt routes by whether the user wants the format rule or the meaning-encoding decision\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semantic-relations owns the typed-connection vocabulary between concepts (IS-A, PART-OF, thematic roles); semantics owns the meaning encoding for an individual identifier or signal — the same 'what does this mean?' prompt routes by whether the trigger is the relation between things or the encoding of one thing\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"microcopy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"microcopy owns specific in-product UI-text patterns (button labels, empty states, tooltips, dialogs, toasts); semantics owns the underlying meaning-encoding rules that apply to any name or signal — the same 'rewrite this UI text' prompt routes by whether the trigger is the UX-pattern surface or the cross-domain meaning rule\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"microcopy\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Semantics is to code what road signage is to driving — the sign isn't the road, but bad signage causes crashes even when the road is fine. A `--light-blue` token that breaks on dark mode is the equivalent of 'Turn Left at the Big Tree' as a road sign: it worked when the tree was there; the semantics depended on the world, not the sign system.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Semantics — applied to software — is the discipline of *meaning encoding* in identifiers and signals: function names, variable names, design tokens, HTTP status codes, version numbers, commit messages, branded types, and the small textual artefacts that communicate intent to humans and machines. Drawing from Domain-Driven Design's *ubiquitous language* (Evans 2003), Don Norman's affordance theory, semantic versioning, and the broader tradition that treats names as contracts, it commits to the view that every visible identifier is a micro-decision whose meaning compounds across the codebase.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/semantics/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/semantics/SKILL.md
+---
+
+# Semantics
+
+## Coverage
+
+Cross-domain semantic thinking for all naming and meaning decisions:
+
+- **Naming in code** — the fundamental what + why principle, naming smells (Peter Hilton's seven categories), DDD ubiquitous language, scalar/count/collection/boolean rules
+- **Semantic versioning** — SemVer 2.0.0 (MAJOR.MINOR.PATCH), what counts as breaking, SemVer vs CalVer, pre-release tags
+- **Semantic commit messages** — Conventional Commits format, type catalog (`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`), breaking-change syntax, the SemVer-from-commits automation chain
+- **Semantic CSS** — purpose-not-appearance class names, BEM (`.block__element--modifier`), three-layer design-token architecture (primitive → semantic → component)
+- **Semantic data modeling** — column-naming rules (unit suffixes, boolean prefixes, timestamp suffixes), semantic types beyond primitives, branded TypeScript types, parse-don't-validate
+- **Semantic UI / UX** — Don Norman affordances and signifiers, semantic color (with the never-color-alone rule), microcopy semantics
+- **Semantic APIs** — REST resource naming (nouns + HTTP verbs, plural collections, kebab-case, max-2-nesting), HTTP status codes as semantic signals (the never-200-with-error-body rule), GraphQL naming
+- **Universal anti-patterns** — generic names, semantic drift, misleading names, appearance-based names, abbreviation ambiguity, cargo-cult naming
+
+## Philosophy
+
+Every name is a micro-decision that compounds across the codebase. A function called `process(data)` forces every future reader to open the implementation to understand its purpose. A design token called `--light-blue` breaks the moment someone adds dark mode. An API returning HTTP 200 with an error body confuses every consumer. These are not style preferences — they are semantic failures that create real debugging time and real misunderstandings.
+
+This skill exists because naming quality degrades silently. No test catches `handleRefresh()` being reused for too many unrelated actions. No linter flags `--big-spacing`. No CI gate rejects `employee2`. Without explicit semantic rules loaded at decision time, agents default to the first name that compiles rather than the name that communicates. The discipline is to make meaning a first-class artifact, not a residue.
+
+The mental model: a `Sign` (the name) acquires meaning from its `Referent` (what it points to) and from `Convention` (the shared agreement). `Affordance` (what the name implies you can do) is the bridge between sign and user expectation. **Semantic drift** happens when referents change but signs do not — a silent lie in the code, the kind no test catches.
+
+> Semantics is to code what road signage is to driving — the sign isn't the road, but bad signage causes crashes even when the road is fine.
+
+## When to Use
+
+- Naming variables, functions, classes, files, or database columns
+- Designing API endpoints, error codes, or status systems
+- Choosing CSS class names or design-token names
+- Writing commit messages or versioning releases
+- Designing UI labels, error messages, or microcopy quality bars
+- Modeling data with domain language and branded types
+- Reviewing code for naming quality
+
+---
+
+## 1. Semantic Naming in Code
+
+### The Fundamental Principle
+
+A name must encode **what** something is and **why** it exists. The reader should never need to read the implementation to understand the purpose.
+
+### Rules
+
+| Rule | Bad | Good | Why |
+|------|-----|------|-----|
+| Use full words | `calc()`, `mgr`, `btn` | `calculateProfitAndMargin()`, `manager`, `button` | Abbreviations are ambiguous (`auth` = authentication or authorization?) |
+| Encode intent | `data`, `info`, `result` | `unpaidInvoices`, `customerProfile`, `validationErrors` | Generic names carry zero information |
+| Use domain language | `UserRequestsProduct` | `customerPlacesOrder` | Match stakeholder vocabulary (DDD ubiquitous language) |
+| Name the distinction | `employee`, `employee2` | `manager`, `recentHire` | Numeric suffixes hide the actual difference |
+| Scalars need qualifiers | `store = "text"` | `storeName = "text"` | `store` implies an object, not a string |
+| Counts need suffixes | `products = 0` | `productCount = 0` | `products` implies a collection |
+| Collections use plurals | `orderList` | `orders` | The data structure already implies "list" |
+| Booleans read as questions | `active` | `isActive`, `hasOrders`, `canEdit` | Reads naturally in conditionals |
+
+### Naming Smells (Peter Hilton's catalog)
+
+1. **Meaningless** — `foo`, `bar`, `tmp`, `x`
+2. **Abstract** — `data`, `object`, `thing`, `item`
+3. **Numeric suffixes** — `employee2` hides the distinction
+4. **Abbreviations** — `acc` (accumulator? accuracy? account?)
+5. **Vague verbs** — `get`, `process`, `handle`, `manage` say nothing about behavior
+6. **Type-encoded** — `array`, `string`, `int` as variable names
+7. **Weasel suffixes** — `Info`, `Data`, `Manager`, `Helper`, `Utils`, `Base`, `Entity`
+
+### DDD Ubiquitous Language
+
+Core domain classes (entities, value objects, events, services) must use business terminology. Zero tolerance for weasel words. Technical terms are acceptable only in infrastructure classes where no domain equivalent exists.
+
+**Translation tax**: every time a developer mentally translates between code vocabulary and business vocabulary, cognitive overhead accumulates — and it compounds across teams and codebase lifetime.
+
+---
+
+## 2. Semantic Versioning (SemVer 2.0.0)
+
+### Format: `MAJOR.MINOR.PATCH`
+
+| Increment | When | Example |
+|-----------|------|---------|
+| **MAJOR** | Backward-incompatible API changes | Removing a method, changing return type |
+| **MINOR** | New backward-compatible functionality | Adding an endpoint, new optional param |
+| **PATCH** | Backward-compatible bug fixes only | Fixing a calculation, patching a security issue |
+
+### What Constitutes a Breaking Change
+
+- Removing a public method, class, endpoint, or field
+- Changing return types or parameter types
+- Changing default behavior users depend on
+- Renaming public APIs without aliases
+- Changing serialization format
+- **NOT breaking**: adding optional params, new endpoints, new types
+
+### SemVer vs CalVer
+
+| Aspect | SemVer | CalVer |
+|--------|--------|--------|
+| Encodes | API compatibility intent | Release timeline |
+| Best for | Libraries, APIs, packages | OS releases, browsers, enterprise |
+| Weakness | Subjective "what's breaking?" | No compatibility signal |
+
+### Pre-release tags
+
+`1.0.0-alpha.1`, `1.0.0-beta.2`, `1.0.0-rc.1`
+
+---
+
+## 3. Semantic Commit Messages (Conventional Commits)
+
+### Format: `type(scope): description`
+
+| Type | Purpose | SemVer Bump |
+|------|---------|------------|
+| `feat` | New feature | MINOR |
+| `fix` | Bug fix | PATCH |
+| `docs` | Documentation only | — |
+| `style` | Formatting, no logic change | — |
+| `refactor` | Code change, no feature/fix | — |
+| `perf` | Performance improvement | PATCH |
+| `test` | Adding/fixing tests | — |
+| `build` | Build system, dependencies | — |
+| `ci` | CI configuration | — |
+| `chore` | Maintenance, no source change | — |
+
+**Breaking changes** — add `!` after the type or `BREAKING CHANGE:` in the footer → MAJOR bump.
+
+```
+feat(auth)!: replace session tokens with JWT
+
+BREAKING CHANGE: Session-based auth removed. All clients must use Bearer tokens.
+```
+
+**Automation chain**: Conventional Commits → semantic-release → changelog → publish. Fully automated versioning from commit messages.
+
+---
+
+## 4. Semantic CSS
+
+### Class Names Describe Purpose, Not Appearance
+
+| Bad (appearance) | Good (purpose) |
+|-----------------|----------------|
+| `.red-text` | `.error-message` |
+| `.left-sidebar` | `.navigation` |
+| `.big-button` | `.primary-action` |
+| `.mt-4` (alone) | `.card__spacing` (with utility supplement) |
+
+### BEM: `.block__element--modifier`
+
+Names encode component structure. `.card__title` belongs to `.card` without reading HTML.
+
+### Design-Token Naming: Three-Layer Architecture
+
+```css
+/* Layer 1: Primitive (raw values, no meaning) */
+--blue-500: oklch(0.62 0.18 260);
+--spacing-4: 1rem;
+
+/* Layer 2: Semantic (purpose-driven) */
+--color-text-primary: var(--grey-900);
+--color-bg-danger: var(--red-100);
+--spacing-component-gap: var(--spacing-4);
+
+/* Layer 3: Component (scoped to specific component) */
+--button-bg-hover: var(--color-bg-interactive-hover);
+--card-border-radius: var(--radius-md);
+```
+
+**Rule**: UI code references *semantic* tokens. Semantic tokens reference *primitives*. Primitives hold raw values. Never skip a layer.
+
+**Anti-patterns**: `--light-blue` (breaks on rebrand), `--color-1` (meaningless), `--homepage-hero-cta-bg` (too coupled to one location).
+
+---
+
+## 5. Semantic Data Modeling
+
+### Column-Naming Rules
+
+| Rule | Bad | Good |
+|------|-----|------|
+| Describe what, not where | `external_price` | `retail_price_cents` |
+| Include unit | `weight` | `weight_grams` |
+| Include precision | `revenue` | `revenue_cents` (integer) |
+| Boolean prefix | `active` | `is_active` |
+| Timestamp suffix | `created` | `created_at` |
+
+### Semantic Types (Beyond Primitives)
+
+A raw `string` can hold an email, URL, SQL query, or credit-card number — semantically different despite identical type. Semantic types make illegal states unrepresentable:
+
+| Semantic Type | Underlying | Why Distinct |
+|--------------|------------|--------------|
+| `Money` | `{ amount: number, currency: string }` | Prevents mixing currencies |
+| `Email` | validated `string` | Ensures format, enables operations |
+| `OrderId` | branded `string` | Prevents passing a `UserId` where `OrderId` expected |
+| `Percentage` | `number` (0–100 or 0–1) | Prevents 50 vs 0.5 confusion |
+
+### Branded Types in TypeScript
+
+```typescript
+type OrderId = string & { readonly __brand: 'OrderId' };
+type UserId  = string & { readonly __brand: 'UserId' };
+
+function getOrder(id: OrderId): Order { /* ... */ }
+
+// Compile error: UserId is not assignable to OrderId
+getOrder(userId);
+```
+
+### Parse, Don't Validate
+
+Instead of checking data after the fact, parse it into a type that *guarantees* validity:
+
+```typescript
+// Bad: validate then trust
+function processEmail(input: string) {
+  if (!isValidEmail(input)) throw new Error('Invalid email');
+  sendEmail(input); // input is still just string
+}
+
+// Good: parse into semantic type
+function parseEmail(input: string): Email | null {
+  return isValidEmail(input) ? (input as Email) : null;
+}
+```
+
+---
+
+## 6. Semantic UI / UX
+
+### Affordances and Signifiers (Don Norman)
+
+- **Affordance** — what an object allows you to do (a button affords pressing)
+- **Signifier** — what communicates the affordance (the button's raised appearance, shadow, cursor change)
+
+Semantic UI ensures signifiers match affordances: clickable things look clickable, draggable things look draggable, disabled things look disabled.
+
+### Semantic Color
+
+| Color | Western Meaning | Risk |
+|-------|----------------|------|
+| Red | Danger, error, stop, loss | Green/red pair fails for ~8% of males (deuteranopia) |
+| Green | Success, go, profit, safe | See above |
+| Yellow / Amber | Warning, caution, pending | Low contrast on white backgrounds |
+| Blue | Information, link, trust | Overloaded — can mean anything neutral |
+| Grey | Disabled, inactive, secondary | Must have sufficient contrast |
+
+**Rule**: color must never be the *sole* differentiator. Always pair with icon, text, or shape.
+
+### Microcopy Semantics
+
+- **Button labels** — verbs with clear objects: "Save changes" not "Submit"
+- **Error messages** — name what broke + how to fix: "Password must be 8+ characters" not "Invalid input"
+- **Confirmations** — name what will happen: "Delete 3 orders permanently?" not "Are you sure?"
+- **Empty states** — explain value + provide action — not just "No data"
+
+For the full UX-text pattern catalog (button label rules, empty-state structure, tooltip rules, dialog rules, toast rules), use the dedicated `microcopy` skill — semantics owns only the underlying meaning rule.
+
+---
+
+## 7. Semantic APIs
+
+### REST Resource Naming
+
+| Rule | Bad | Good |
+|------|-----|------|
+| Nouns, not verbs | `/getOrders` | `/orders` |
+| Plural for collections | `/order` | `/orders` |
+| HTTP method = verb | `POST /createUser` | `POST /users` |
+| Kebab-case | `/orderItems` | `/order-items` |
+| Max 2 nesting levels | `/a/1/b/2/c/3` | `/orders/123/items` |
+
+### HTTP Status Codes as Semantic Signals
+
+| Family | Semantic Meaning | Responsibility |
+|--------|------------------|---------------|
+| 2xx | Success | Server fulfilled the request |
+| 3xx | Redirect | Client must follow |
+| 4xx | Client error | Client's fault |
+| 5xx | Server error | Server's fault |
+
+**Never return HTTP 200 with an error body.** The status code IS the semantic signal.
+
+### GraphQL Naming
+
+- Types: PascalCase (`Order`, `LineItem`)
+- Fields: camelCase (`totalRevenue`, `createdAt`)
+- Mutations: verb + noun (`createOrder`, `updateShippingAddress`)
+- Enums: SCREAMING_SNAKE (`ORDER_STATUS`, `PAYMENT_METHOD`)
+
+---
+
+## 8. Universal Anti-Patterns
+
+| Anti-Pattern | Domains Affected | Fix |
+|--------------|------------------|-----|
+| **Generic names** (`data`, `info`, `utils`, `misc`, `helpers`) | Code, files, folders, CSS, API | Replace with domain-specific purpose |
+| **Semantic drift** (name no longer matches behavior) | Code, API, DB, tokens | Rename in same commit as behavior change |
+| **Misleading names** (`isReady` returns a promise, not a boolean) | Code, API | Name must match return type and behavior |
+| **Appearance-based names** (`.red`, `leftColumn`, `bigFont`) | CSS, tokens, components | Name purpose, not presentation |
+| **Abbreviation ambiguity** (`auth`, `temp`, `proc`, `val`) | All domains | Use full words; abbreviate only universals (`id`, `url`, `api`) |
+| **Cargo-cult naming** (copying patterns without understanding) | All domains | Every name must be justified for *this* context |
+
+---
+
+## Verification
+
+After applying this skill, verify:
+
+```text
+SEMANTICS CHECK
+===============
+[ ] Every name encodes what + why (no data/info/temp/misc)
+[ ] Domain language matches stakeholder vocabulary
+[ ] No abbreviation ambiguity (auth, proc, val, acc)
+[ ] Booleans read as questions (is/has/can/should)
+[ ] CSS classes describe purpose, not appearance
+[ ] Design tokens use the 3-layer architecture (primitive → semantic → component)
+[ ] API endpoints use nouns, HTTP methods as verbs
+[ ] HTTP status codes match semantic meaning (no 200 with error body)
+[ ] Commit messages follow Conventional Commits format
+[ ] Color is never the sole status differentiator
+[ ] Semantic types prevent illegal states (branded types for IDs)
+[ ] Version bumps match SemVer rules (breaking = MAJOR)
+[ ] Currency-as-integer columns end in `_cents` (or equivalent unit suffix)
+```
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `linguistics` | Word morphology, compound-word ordering, polysemy resolution at the identifier level, audience register, blame-free phrasing. Linguistics owns the form rules; semantics owns the meaning encoding. |
+| `naming-conventions` | Deciding the casing format for an artifact kind (kebab vs camel vs snake vs Pascal). Naming-conventions owns the convention; semantics owns the meaning encoding under it. |
+| `semantic-relations` | Typing the connection *between* two concepts (IS-A, PART-OF, thematic, causal). Semantic-relations owns the relation vocabulary; semantics owns the encoding of one identifier or signal. |
+| `microcopy` | The specific UX-text pattern (button labels, empty states, tooltips, dialogs, toasts). Microcopy owns the patterns; semantics owns the cross-domain meaning rule applied to many surfaces. |
+| `a11y` | Accessibility-label auditing (aria-label correctness, focus-state semantics, screen-reader announcement). A11y owns accessibility contracts; semantics owns naming-quality contracts. |
+| `code-review` | Reviewing a specific PR for correctness, security, or quality across many concerns. Code-review uses semantics as one input; it does not own the meaning rules. |
+| (a glossary skill) | Defining the canonical meaning of a domain term. A glossary owns the definition; semantics owns the consistent application of the definition in names and signals. |
+| (a taxonomy skill) | Designing the classification structure itself (hierarchy vs facet, IS-A vs PART-OF tree shape). Taxonomy owns the structure; semantics owns the names inside it. |
+
+## Key Sources
+
+- Evans, E. (2003). *Domain-Driven Design: Tackling Complexity in the Heart of Software*. Addison-Wesley. The canonical statement of *ubiquitous language* — that domain code must use the same terms as domain experts — and the value-object pattern for encoding meaning in types.
+- Norman, D. A. (2013). *The Design of Everyday Things* (Revised and Expanded Edition). Basic Books. The foundational affordance / signifier framework; applied directly to the discipline of matching identifier names to actual behavior.
+- Hilton, P. (2017). ["Naming Smells."](https://hilton.org.uk/blog/naming-smells) Seven categories of names that destroy readability: meaningless, abstract, numeric-suffix, abbreviation, vague-verb, type-encoded, weasel-suffix. The practitioner reference for naming review.
+- Preston-Werner, T. [Semantic Versioning 2.0.0](https://semver.org/). The normative specification for MAJOR.MINOR.PATCH; the convention that makes API-compatibility intent machine-readable across package ecosystems.
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/). The specification for `type(scope): description` commit messages; the foundation for automated changelog generation and SemVer-from-commits tooling.
+- King, A. (2019). ["Parse, don't validate."](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) The reference statement of the parse-don't-validate pattern; encode meaning in types rather than checking it at use sites.
+- IETF. [RFC 9110: HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110). The normative specification of HTTP status code semantics (2xx / 4xx / 5xx) and the body-vs-status separation of concerns.
+- Martin, R. C. (2008). *Clean Code: A Handbook of Agile Software Craftsmanship*. Prentice Hall. Chapter 2 ("Meaningful Names") is one of the most widely cited practitioner statements of naming discipline.
+- Fowler, M. (2010). ["DomainLanguage."](https://martinfowler.com/bliki/DomainLanguage.html) The bridge between DDD's ubiquitous-language principle and day-to-day engineering practice.
+- Hejlsberg, A., et al. Microsoft. [TypeScript Handbook — Branded Types pattern](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html). The implementation surface for branded types and other meaning-encoding patterns in TypeScript.

package/marketplace/skills/semiotics/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: semiotics
+description: "Use when designing or auditing icon systems, colors/badges/shapes, visual metaphors, interface signs, or naming-plus-visual surfaces that users misread. Covers semiotic reasoning across icon/index/symbol, signifier/signified, denotation/connotation/myth, color/shape/position/iconography, affordances, code/API signifiers, and semiotic-coherence audits. Do NOT use for actual UI wording (use `microcopy`), palette/typography craft (use `visual-design-foundations`), accessibility or contrast compliance (use `a11y`), formal class hierarchies, or word morphology rules."
+license: MIT
+compatibility: "Stack-agnostic sign-system analysis. The Peirce / Saussure / Barthes models, color-as-sign rules, iconography principles, and affordance taxonomy apply to any UI; example surfaces use generic e-commerce framings — substitute the equivalents from your domain."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.1.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/semantics\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"sign-system analysis\\\\\\\",\\\\\\\"icon polysemy\\\\\\\",\\\\\\\"signifier signified mapping\\\\\\\",\\\\\\\"denotation versus connotation\\\\\\\",\\\\\\\"affordance signifier match\\\\\\\",\\\\\\\"icon-index-symbol trichotomy\\\\\\\",\\\\\\\"visual metaphor clarity\\\\\\\",\\\\\\\"color connotation audit\\\\\\\",\\\\\\\"cross-surface sign drift\\\\\\\",\\\\\\\"semiotic coherence audit\\\\\\\",\\\\\\\"anti-affordance design\\\\\\\",\\\\\\\"icon-system consistency\\\\\\\",\\\\\\\"abstract-mark opacity\\\\\\\",\\\\\\\"sign-conflict detection\\\\\\\",\\\\\\\"visual-meaning audit\\\\\\\",\\\\\\\"code-and-api semiotics\\\\\\\"]\",\"examples\":\"[\\\\\\\"our dashboard uses green for both revenue increase and cost increase, so users read both as good — what semiotic failure is that and how should we correct it?\\\\\\\",\\\\\\\"we use a gear icon for settings on one page and preferences on another — is this just a naming issue, or an interface sign conflict?\\\\\\\",\\\\\\\"a disabled button still looks clickable because only the color changed — which signifier or affordance rule is failing?\\\\\\\",\\\\\\\"we need an icon for reconciliation in a financial workflow — which metaphors are available, and when must text stay paired with the icon?\\\\\\\",\\\\\\\"an API function is named processData() — from a sign-system perspective, what is wrong with that name?\\\\\\\",\\\\\\\"audit this status-badge color system for denotation vs connotation conflicts\\\\\\\",\\\\\\\"explain why users keep clicking a non-interactive label that looks like a link\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"I need formal class hierarchies, axioms, and what-exists rules for our knowledge base\\\\\\\",\\\\\\\"I need physical database schema design and relationship constraints\\\\\\\",\\\\\\\"I need the relation type between two concepts — synonymy, polysemy, or meronymy\\\\\\\",\\\\\\\"draft the exact wording for a button label or tooltip after the sign system is chosen\\\\\\\",\\\\\\\"give me the live color-token values, APCA contrast math, and palette enforcement\\\\\\\",\\\\\\\"explain the morphology rule behind verb-first function names\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semantics owns meaning encoding for individual textual identifiers and signals (function names, design tokens, HTTP status codes, branded types, SemVer, conventional commits); semiotics owns sign-system analysis for visual + textual sign systems (icons, color as sign, affordances, signifier/signified mappings) — the same 'what does this mean?' prompt routes by whether the trigger is one identifier's encoding or a multi-channel sign system\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"microcopy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"microcopy owns the actual UI wording (button labels, empty states, tooltips, dialogs); semiotics owns the sign-system reasoning that determines what the words and accompanying visual signs should communicate — the same 'fix this UI element' prompt routes by whether the trigger is the wording itself or the sign system the wording sits inside\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semantic-relations owns the typed connections between concepts (IS-A, PART-OF, thematic roles); semiotics owns the signifier-to-signified mapping in interface and naming surfaces — the same 'how does this relate to that?' prompt routes by whether the trigger is a conceptual relation type or a sign-system relationship\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"visual-design-foundations owns visual craft decisions such as palette, type, spacing, and hierarchy; semiotics owns what those signs communicate\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"intent-recognition\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Semiotics is to interface design what choreography is to a play — the words are the script, but the actor's stance, hand position, gaze direction, and proximity to other actors are the choreography. A line that lands flat with the wrong choreography lands well with the right one; same words, different signs. A disabled button that uses only a paler color (signifier too quiet) is a stage actor whispering an exit cue the audience cannot hear.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Semiotics is the study of *sign systems* — how signifiers (perceivable forms: icons, colors, shapes, positions, words) point to signifieds (concepts, states, actions) via convention, resemblance, or causal connection. Applied to interfaces, it is the discipline of designing and auditing the multi-channel sign systems through which a product communicates with its users. Drawing from Peirce's icon/index/symbol trichotomy, Saussure's signifier/signified dyad, Barthes' denotation/connotation/myth layering, and Norman's affordance theory, it treats every interface element as a sign whose meaning is constructed, not given.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/semiotics/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/semiotics/SKILL.md
+---
+
+# Semiotics
+
+## Coverage
+
+Semiotic analysis as the study of sign systems in software interfaces and communication. Covers:
+
+- **Foundational models** — Peirce's icon / index / symbol trichotomy; Saussure's signifier / signified dyad; Barthes' denotation / connotation / myth layers
+- **Visual semiotics for interfaces** — color as sign (denotation + connotation, with the never-color-alone rule), shape and position as sign channels (top-left, top-right, bottom-right, circle, triangle, pill)
+- **Iconography as a sign system** — consistency, metaphor clarity, pairing rules, system coherence; common breakdowns (icon polysemy, opacity, cultural collision, obsolete metaphor)
+- **Affordance theory** — real affordance, perceived affordance, signifier, anti-affordance; the rule that disabled states need a strong anti-affordance
+- **Code and API semiotics** — naming, variable, endpoint, and error-message signs; the rule that vague names like `processData()` are signifier failures even when the implementation works
+- **Semiotic-coherence audit** — the checklist for reviewing a surface across color, icon, affordance, and cross-surface consistency
+
+The skill operates *above* microcopy execution and color-token math, and *below* formal ontology. It owns the question "what does this sign communicate to a user?", not "what should the button say?", "what hex value is this?", or "what class hierarchy do these things belong to?".
+
+## Philosophy
+
+Every interface element is already communicating, whether the designer intended it to or not. Semiotics exists to make that communication explicit and coherent. A button that looks clickable but is disabled, a green badge that signals "good" when the metric is actually worsening, or a gear icon that means different things on different pages are not visual quirks; they are sign failures that erode user trust one micro-misread at a time.
+
+The core rule is: **one signifier should point clearly to one intended signified within a given system context.** The more a sign drifts, the more users (and agents) are forced to infer meaning from guesswork rather than from the system itself. Sign drift compounds — a single ambiguous icon is a small cost; ten ambiguous icons across a product is a learned distrust of the entire surface.
+
+This skill is sign *analysis*, not visual *craft*. It tells you whether a sign communicates the right meaning. It does not tell you how to lay out the screen, what hex value to use, what class hierarchy to formalize, or what wording to put on a button. Each of those belongs to a different skill in the design / language / data cluster.
+
+## When to Use
+
+- Designing or auditing icon systems
+- Checking whether a color, badge, or shape communicates the wrong judgment
+- Explaining why users misread a button, state, or symbol
+- Choosing or critiquing visual metaphors for abstract concepts
+- Auditing naming and interface signs together when a surface feels semantically off
+
+---
+
+## 1. Foundations — How Signs Work
+
+### Peirce's Trichotomy
+
+| Sign type | Relationship to meaning | UI example | Strength |
+|-----------|------------------------|------------|----------|
+| **Icon** | Resembles what it represents | Magnifying glass = search | Intuitive but culturally variable |
+| **Index** | Causally connected to meaning | Loading spinner = something is happening | Direct but context-dependent |
+| **Symbol** | Arbitrary convention | Red = danger, hamburger = menu | Efficient once learned |
+
+Rules:
+
+- Prefer icons for first-use discoverability.
+- Prefer symbols for expert fluency when the convention is already learned.
+- Use indexes when the system needs to signal that a process or state is actively occurring.
+
+### Saussure's Dyad
+
+| Component | Definition | Application |
+|-----------|-----------|-------------|
+| **Signifier** | The perceivable form | Color, shape, text, icon, animation |
+| **Signified** | The concept or meaning | Action, state, category, judgment |
+
+Rules:
+
+- The same signifier should not point to multiple signifieds within one product surface unless that ambiguity is deliberate and documented.
+- Changing the signifier can break learned meaning even if the redesign seems visually improved.
+
+### Barthes' Three Layers
+
+| Layer | What it is | Example |
+|-------|-----------|---------|
+| **Denotation** | Literal reading | Up arrow = increase |
+| **Connotation** | Associated judgment / cultural meaning | Green = positive / good |
+| **Myth** | Systemic or ideological framing | Growth as inherently desirable |
+
+Rules:
+
+- Separate direction from judgment in financial UI. An *increase* is not always *good*.
+- A sign can be denotationally correct while still semantically wrong because the connotation misleads.
+
+---
+
+## 2. Visual Semiotics for Interfaces
+
+### Color as Sign
+
+| Color | Common denotation | Common connotation | Risk |
+|-------|-------------------|--------------------|------|
+| Red | Error, stop, danger | Bad, urgent, loss | Overuse dulls alarm meaning |
+| Green | Success, active, up | Good, growth, healthy | Wrong when used for *undesirable* increases |
+| Yellow / Amber | Warning, caution | Attention needed | Easily confused with error |
+| Blue | Information, trust, link | Calm, corporate, neutral authority | Can become semantically empty if overused |
+| Grey | Inactive, secondary, disabled | Neutral, quiet | May fail as an anti-affordance if too subtle |
+
+Rules:
+
+- Color should not be the *only* sign channel for important meaning.
+- Audit color decisions at both denotation and connotation levels.
+- Live token values, contrast compliance, and visual craft belong to `a11y` or `visual-design-foundations`; semiotics evaluates only whether the *sign* itself is coherent.
+
+### Shape and Position as Sign
+
+| Sign channel | Common reading |
+|--------------|----------------|
+| Top-left placement | Primary or first-scanned element |
+| Top-right placement | Tools, account, utility actions |
+| Bottom-right placement | Primary CTA in a dialog |
+| Circle | Status, avatar, completion |
+| Triangle / arrow | Direction, expansion, movement |
+| Pill / badge | Category, state, count |
+
+Rules:
+
+- Position and shape carry meaning even without text; treat them as part of the sign system.
+- If a layout or component breaks a strong convention, ensure the surrounding cues are strong enough to retrain the interpretation.
+
+---
+
+## 3. Iconography as a Sign System
+
+| Principle | Rule |
+|-----------|------|
+| **Consistency** | Same concept = same icon across the product |
+| **Metaphor clarity** | The metaphor should be legible without specialist training |
+| **Pairing** | Abstract or unfamiliar icons need text pairing until learned |
+| **System coherence** | Use one icon family unless there is a compelling reason not to |
+
+Common breakdowns:
+
+- **Icon polysemy** — one icon means several things
+- **Opacity** — abstract mark with no clear signified
+- **Cultural collision** — metaphor fails outside one audience's assumptions
+- **Obsolete metaphor** — the convention is still learned by some but dead to others (e.g., the floppy-disk save icon)
+
+---
+
+## 4. Affordance Theory
+
+| Concept | Application |
+|---------|-------------|
+| **Real affordance** | What the element can actually do |
+| **Perceived affordance** | What the element appears to allow |
+| **Signifier** | The cue that tells the user action is possible |
+| **Anti-affordance** | The cue that tells the user action is *not* possible |
+
+Rules:
+
+- If an element looks interactive, it should be interactive.
+- Disabled states need a strong anti-affordance, not just a mild color change.
+- Semiotic failures most often appear when the signifier and the true affordance disagree.
+
+---
+
+## 5. Code and API Semiotics
+
+Semiotics also applies to textual and code-facing signs.
+
+| Sign surface | Semiotic question |
+|--------------|-------------------|
+| Function name | Does the signifier actually tell me what the behavior is? |
+| Variable name | Does the label point clearly to the value's meaning? |
+| API endpoint | Does the route name communicate the resource / action correctly? |
+| Error message | Does it communicate both what happened and how to respond? |
+
+**Rule**: a vague name like `processData()` is a signifier failure even when the implementation works. The reader has to *open the function* to learn its meaning — which is exactly the inference cost a good sign eliminates.
+
+This overlaps with `semantics` (which owns identifier-level meaning encoding); semiotics adds the sign-system lens — *is the same concept signed consistently across both code names and visual interface elements?*
+
+---
+
+## 6. Semiotic-Coherence Audit
+
+Use this checklist when reviewing a surface:
+
+- Does each color carry one stable meaning across the product?
+- Does each icon represent one intended concept?
+- Do interactive elements look interactive?
+- Do disabled states look unavailable rather than merely quiet?
+- Are abstract concepts paired with enough textual support?
+- Is the same concept being signed consistently across UI and code-facing surfaces?
+
+---
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/semiotics.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/semiotics.json). The checklist below is the authoring gate for sign-system decisions; the eval file is the grader surface.
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] No signifier points to multiple unintended signifieds within the same system context
+- [ ] Important interface meanings are not encoded through color alone
+- [ ] Interactive and non-interactive states have distinct affordance signals
+- [ ] Icon metaphors are coherent, learnable, and consistent across surfaces
+- [ ] Direction (denotation) and judgment (connotation) are separated in financial / metric UI
+- [ ] Code-facing signs (function, variable, endpoint names) are not vague signifier failures
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `microcopy` | Drafting the actual button labels, empty states, tooltips, or toasts. Microcopy owns the wording; semiotics owns the sign system the wording lives inside. |
+| `semantics` | Deciding the meaning encoding of a single identifier, design token, HTTP status code, or commit type. Semantics owns identifier-level meaning; semiotics owns the multi-channel sign system. |
+| `semantic-relations` | Typing the connection between two concepts (IS-A, PART-OF, thematic, causal). Semantic-relations owns concept-to-concept relations; semiotics owns sign-to-meaning mappings. |
+| `linguistics` | Word morphology, compound-word ordering, abbreviation policy. Linguistics owns word-form rules; semiotics owns broader sign systems including visual ones. |
+| `a11y` | Auditing aria-label correctness, focus management, screen-reader semantics. A11y owns accessibility contracts; semiotics may inform them but does not own them. |
+| `visual-design-foundations` | Palette, typography, spacing, hierarchy, craft quality, and motion feel. Visual-design-foundations owns visual craft; semiotics asks what the visual element *signifies*. |
+| (an ontology skill) | Formal class hierarchies, existence axioms, reasoning constraints. Ontology owns formal classification; semiotics owns sign meaning in interfaces. |
+
+## Key Sources
+
+- Peirce, C. S. (1931-1958). *Collected Papers of Charles Sanders Peirce* (8 vols.). Harvard University Press. The original statement of the icon / index / symbol trichotomy; the foundational typology of sign-to-referent relations that all later interface-semiotics work builds on.
+- Saussure, F. de (1916). *Cours de linguistique générale* / *Course in General Linguistics*. Payot. The signifier/signified dyad and the principle that meaning is constituted by systems of contrast — the structural foundation for sign-system analysis.
+- Barthes, R. (1957). *Mythologies*. Éditions du Seuil. The three-layer denotation / connotation / myth analysis; the canonical demonstration that signs carry cultural and ideological meaning beyond literal reading.
+- Eco, U. (1976). *A Theory of Semiotics*. Indiana University Press. The systematic treatment of semiotics as a discipline; cultural codes, sign-production, and the constructed-meaning principle.
+- Norman, D. A. (2013). *The Design of Everyday Things* (Revised and Expanded Edition). Basic Books. The foundational text on affordances and signifiers for interface design; the discipline of matching visual cues to actual interaction possibilities.
+- Gibson, J. J. (1979). *The Ecological Approach to Visual Perception*. Houghton Mifflin. The original psychological account of affordances — what the environment offers to a perceiver — that Norman adapted to design.
+- Nielsen Norman Group. ["Icon Usability"](https://www.nngroup.com/articles/icon-usability/). Empirical UX research on icon polysemy, opacity, and the icon-plus-text pairing rule; the practitioner reference for icon-system design.
+- W3C. [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) — Use of Color (Success Criterion 1.4.1). The international standard expression of the never-color-alone principle.
+- Frutiger, A. (1989). *Signs and Symbols: Their Design and Meaning*. Watson-Guptill. The reference work on visual sign design from typography to pictograms; foundational for icon-system vocabulary work.
+- Krug, S. (2014). *Don't Make Me Think, Revisited*. New Riders. The practitioner statement of the cognitive-cost principle in interface signs; the empirical observation that users do not read signs analytically — they pattern-match, and the sign system must support that.