Semantics

Semantics

Concept of the skill

Semantics in software is meaning encoding: every name, status code, version number, commit type, token, telemetry attribute, tool definition, and typed value is a sign that points at a referent under a convention.

Coverage

Cross-domain semantic thinking for all naming and meaning decisions:

• Naming in code — the fundamental what + why principle, verb-prefix return/side-effect contracts (get/find/fetch/parse/ensure/assert), naming smells (Peter Hilton's seven categories), machine-reader naming smells, DDD ubiquitous language, scalar/count/collection/boolean rules
• Semantic versioning — SemVer 2.0.0 (MAJOR.MINOR.PATCH), the declared-public-API precondition, what counts as breaking, the 0.y.z initial-development rule, deprecation-as-MINOR, precedence, Hyrum's Law, SemVer vs CalVer
• Semantic commit messages — Conventional Commits format, type catalog (feat, fix, docs, style, refactor, perf, test, build, ci, chore), the spec-vs-tooling SemVer mapping, 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), the DTCG stable interchange format ($value/$type/$description/$deprecated, .tokens), cascade-layer (@layer) names and order as an explicit priority signal
• Semantic data modeling — column-naming rules (unit suffixes, boolean prefixes, timestamp/instant/date/range distinctions), semantic types beyond primitives, branded TypeScript types (string-tag and unique symbol), smart constructors, parse-don't-validate
• Semantic UI / UX — Don Norman affordances and signifiers, semantic HTML element choice (<button> vs <div onclick>, <time datetime>, lists), semantic color (with the never-color-alone rule), signifier checks, 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 + within-family disambiguation), RFC 9457 Problem Details for machine-readable error payloads, GraphQL naming and schema semantics (field/enum/nullability as wire contract, @deprecated, @oneOf, the media-type-dependent transport-status rule)
• Semantic tool, telemetry & schema contracts for machine readers — LLM tool/function names, descriptions as routing prompts, argument enums and units, destructive-operation legibility, result-field contracts, OpenTelemetry observability-attribute conventions, prompt-artifact boundary names, and versioning machine-read artifacts
• Universal anti-patterns — generic names, semantic drift, misleading names, appearance-based names, abbreviation ambiguity, cargo-cult naming, machine-reader drift, unit drift, enum reuse

Philosophy of the skill

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 audience for names has widened. Names are no longer read only by humans and compilers — LLM-backed routers, agents, and tool-selection layers now read tool names, function names, and field names to decide what to invoke; dashboards and alerts read telemetry attribute names no human wrote at emit time; design-token transformers and GraphQL introspection clients read names as wire contracts. An ambiguous provider or a vague process degrades automated tool selection the same way it degrades a human reader, so semantic precision is now also a machine-routing concern, not only a readability one. (For the design of the tool/function interface itself, defer to agent-engineering and tool-call-flow; semantics owns only whether the chosen words encode the right meaning.)

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.

Semantic Audit Workflow (Sign · Referent · Convention)

When auditing any name, status, version, token, schema field, tool, or signal, run the same repeatable check — it operationalizes the mental model and works across every domain in this skill:

1. Name the Sign. What is the literal signal? (process(data), 200, --light-blue, feat:, OrderId, get_user, payment.status.)
2. Find the Referent. What does it actually point at now? Read the implementation/behavior, not the name's promise. (Does process reconcile revenue? Did the request actually fail? Does the token resolve to a brand color? Can the tool delete?)
3. Check the Convention. Under the shared agreement for this artifact kind (SemVer spec, Conventional Commits, RFC 9110, DTCG, OpenTelemetry conventions, DDD ubiquitous language, the local API style), does the Sign correctly encode the Referent?
4. Predict the inference. Would a competent reader, client, design tool, router, or LLM infer the actual referent from the sign without opening implementation details?
5. Repair the mismatch. Fix the Sign, split the Referent, or update the Convention — in the same change as the behavior change so the drift never ships. A comment explaining the lie is not a semantic repair.

A mismatch at step 3/4 is semantic drift — the defect to fix.

When to Use

• Choosing semantically truthful names for variables, functions, classes, files, database columns, events, and types.
• Auditing whether a name still matches the behavior, domain concept, unit, or compatibility promise it now represents.
• Deciding whether one API name, status code, error code, field, or problem type tells the truth (route whole-surface design to api-design and protocol detail to http-semantics).
• Choosing semantic CSS classes, design-token names, or token layers that survive rebrand, dark mode, and component reuse.
• Choosing Conventional Commit type/scope or SemVer bump based on the meaning of a change.
• Modeling domain language with branded/refined types or parse-don't-validate boundaries.
• Auditing whether an LLM tool/function name, telemetry attribute, or prompt-artifact slot truthfully encodes its referent.
• Reviewing UI labels, colors, affordances, and status indicators for meaning alignment before microcopy or a11y checks.
• Reviewing code for naming quality when the problem is the meaning encoded by a name, not the mechanical rename.

Boundary Routing

1. Semantic Naming in Code

The Fundamental Principle

A name must encode what something is, why it exists, and what contract it exposes to readers or tools. The reader should not need to open the implementation to distinguish the domain concept, unit, side effect, lifecycle state, or compatibility signal.

Rules

Verb Prefixes Encode a Return/Side-Effect Contract

A function's leading verb is a promise about its return shape, cost, certainty, and side effects; readers and callers (human and LLM) route on it. Keep the verb honest:

The prefix is the at-a-glance signal; when behavior and prefix disagree, the prefix lies and every caller inherits the wrong expectation. (When the work becomes artifact-specific casing, prefix/suffix policy, or rename mechanics, route to naming-conventions.)

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

Machine-Reader Naming Smells

Names are now read by LLM routers, tool selectors, schema validators, design-token transformers, GraphQL introspection clients, and changelog generators. This adds several smells beyond Hilton's:

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

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 Nuances Agents Often Miss

• SemVer requires a declared public API. If the public API is vague, the version number cannot communicate compatibility truthfully — declare the surface before applying the rules.
• 0.y.z is initial development (SemVer §4): anything MAY change at any time; the public API is not considered stable. Do not read a 0.4 → 0.5 bump as a "safe minor" — many ecosystems (npm by default) treat a 0.y.z MINOR bump as potentially breaking. Version 1.0.0 is what declares a stable public API; it is a semantic commitment, not a maturity badge.
• Deprecating public-API functionality requires a MINOR bump — deprecation is a forward-compatibility signal even before removal. Removing or renaming public API without an alias is MAJOR.
• Precedence: a pre-release version has lower precedence than its normal version (1.0.0-rc.1 < 1.0.0), and build metadata (1.0.0+20130313144700) is ignored when determining precedence (SemVer §11). A release candidate never accidentally outranks the final release; never use build metadata to signal compatibility.
• Hyrum's Law caveat: at sufficient scale, all observable behavior of an API becomes something some consumer depends on, even behavior the written contract never promised. A bug-fix that changes observed output can break real consumers — weigh that before calling it a safe PATCH.

Pre-release tags

1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

SemVer vs CalVer

3. Semantic Commit Messages (Conventional Commits)

Format: type(scope): description

Spec Meaning vs Release-Tool Policy

Only three mappings are normative. Conventional Commits 1.0.0 assigns a SemVer effect to exactly three things: fix → PATCH, feat → MINOR, and a breaking change (! or BREAKING CHANGE: footer) → MAJOR. Every other type is allowed but carries no implicit SemVer effect unless your release tooling defines one (spec §"Summary" + the SemVer-relationship FAQ). The † rows above therefore depend on local configuration: many tools bump nothing for perf/refactor/docs by default, while some configs map perf → PATCH. Do not assert "perf is a PATCH bump" as a property of the spec — it is a property of a particular tool's config.

If one change honestly needs multiple types, split the commit whenever possible so the type remains a truthful signal. If it cannot be split, choose the type that communicates the externally observable change, then use the body/footer for secondary facts.

Breaking changes — add ! after the type/scope or a BREAKING CHANGE: footer → MAJOR bump. The footer token must be uppercase BREAKING CHANGE (or BREAKING-CHANGE); a lowercased "breaking change" is not recognized by tooling. ! and the footer may be used together — the ! is the at-a-glance signal, the footer carries the migration detail.

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. This is the concrete reason the type choice is semantic, not cosmetic: a feature mislabeled chore is silently dropped from the changelog and never triggers the MINOR bump it earned.

4. Semantic CSS

Class Names Describe Purpose, Not Appearance

BEM: .block__element--modifier

Names encode component structure. .card__title belongs to .card without reading HTML.

Design-Token Naming: Three-Layer Architecture

/* 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).

The DTCG interchange format (stable Final Report, 2025.10)

The three-layer architecture above is the authoring discipline; the Design Tokens Community Group (DTCG) format is the vendor-neutral interchange format that lets that discipline travel between tools (Figma, Style Dictionary, Tokens Studio, etc.). It reached its first stable version — a Final Community Group Report, 2025.10, on 2025-10-28 (stable, but explicitly not a W3C Standard); the skill previously cited a /drafts/ URL, which is now superseded. Semantic primitives that matter for naming and meaning:

{
  "color": {
    "text-primary": { "$value": "{grey.900}", "$type": "color", "$description": "Default body text" }
  }
}

• Aliasing is what makes appearance-coupled names wrong — the reference syntax lets one semantic token (--color-bg-danger / color.status.danger.bg) resolve to different primitive values under different themes, so a name baked to one appearance (--light-blue) cannot follow a theme switch. If color.status.success.bg aliases green today and blue tomorrow, the semantic token survives a rebrand because the sign's purpose stayed stable.
• File convention: .tokens / .tokens.json, media type application/design-tokens+json.
• Treat richer theming and specific color-space support (OKLCH / Display-P3 / CSS Color 4) as the consuming tool's capability layered on the format, not as a guarantee the format spec itself makes — verify against the tool you target. For token taxonomy, component APIs, theming governance, and migration, route to design-system-architecture / theme-system-design; semantics owns only whether the names and aliases preserve intended meaning.

Cascade Layers (@layer) — the layer name and order are a priority signal

CSS cascade layers (CSS Cascade Level 5) let you name groups of rules and declare their precedence explicitly, independent of source order or selector specificity. Both halves are semantic — semantics owns only the meaning of the layer names and the priority signal, not selector specificity, @scope, or full cascade mechanics (route those to CSS-architecture / frontend skills):

/* The order statement IS the contract: later layers win. */
@layer reset, base, components, utilities;

@layer components { .card { padding: 1rem; } }
@layer utilities  { .p-0  { padding: 0; } }   /* wins over components, despite equal specificity */

• The layer name encodes intent (reset / base / theme / components / utilities) the same way a semantic token name does — @layer hacks or @layer z1 is the appearance-named --light-blue of the cascade: it says nothing about why its rules should win.
• The @layer name, name, … statement encodes priority — reordering it silently changes which rules win across the whole sheet, with no selector change. Treat that order as a published contract; a reorder is a behavioral change, not a cosmetic one.
• Layer contents must match the layer's promise — component one-offs accumulating inside a tokens layer is layer drift; move the rule to its owning layer.
• Unlayered styles outrank every layer, so "drop it outside a layer to force it to win" is a meaning-defeating escape hatch; an overrides layer should be rare and justified — prefer fixing the owning layer or layer order.

5. Semantic Data Modeling

Column-Naming Rules

Unit and Temporal Naming

Numbers and timestamps are the places where syntax most often lies — a bare type passes every check while the meaning is wrong:

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:

Branded Types in TypeScript

TypeScript is structurally typed: two strings are interchangeable no matter what they mean. A brand adds a phantom, compile-time-only tag so the type system treats OrderId and UserId as distinct. Prefer a reusable helper and a parser/constructor boundary; two brand forms, chosen by stakes:

// Form A — string-tag brand. Covers most app code; one reusable helper.
type Brand<T, Tag extends string> = T & { readonly __brand: Tag };
type OrderId = Brand<string, 'OrderId'>;
type UserId  = Brand<string, 'UserId'>;

function getOrder(id: OrderId): Order { /* ... */ }
getOrder(userId); // Compile error: UserId is not assignable to OrderId

// Form B — unique symbol brand. For libraries / high-stakes domains:
// the tag cannot be forged or collided with from another module.
declare const OrderIdBrand: unique symbol;
type OrderId2 = string & { readonly [OrderIdBrand]: true };

Smart constructor over raw cast. A brand only guarantees distinctness, not validity. Mint branded values through a validating constructor so the cast happens in exactly one audited place — this is the brand's bridge to parse-don't-validate below:

function parseOrderId(input: string): OrderId | null {
  return /^ord_[0-9a-f]{16}$/.test(input) ? (input as OrderId) : null;
}

Rules:

• Brand only values where mixups are plausible and costly: IDs, units, money, URLs, emails, permission scopes, state-machine states.
• Mint branded values at a parser or smart constructor, not by scattering raw casts at call sites.
• Gotcha: the brand is a compile-time fiction. The phantom property does not exist at runtime — never write if (value.__brand === 'OrderId'); it is always undefined. Runtime checks belong in the smart constructor.
• For soundness, narrowing, exhaustiveness, validator choice, and runtime-boundary mechanics, route to type-safety; semantics owns only when a type/brand/unit name encodes the wrong meaning.

Parse, Don't Validate

Instead of checking data after the fact, parse it into a type that guarantees validity:

// 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;
}

The core idea: preserve the knowledge the parser gained in the type, instead of discarding it after a boolean check and re-validating downstream. A parseEmail that returns Email | null pushes the "is this valid?" question to the boundary once; everything past the boundary holds a value whose type already proves validity.

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 HTML — the element choice is the first signal

The HTML element you pick is a meaning declaration, read by browsers, assistive tech, and crawlers before any class or label. A <div onclick> styled to look like a button is the markup equivalent of process(data): it works mechanically but encodes none of the meaning.

Rules:

• Choose the element whose native meaning matches the referent before adding ARIA or JavaScript behavior.
• Class names should describe the nature of the content or component role, not only the desired presentation.
• Do not derive business meaning from opaque id values; use explicit data fields or structured attributes when meaning must be machine-readable.
• Verifying the resulting accessibility contract — roles, focus order, screen-reader announcement, aria-* — belongs to a11y. Semantics flags the <div>-that-should-be-a-<button>; a11y proves the fix is actually accessible.

Semantic Color

Rule: color must never be the sole differentiator. Always pair with icon, text, or shape. (The color-redundancy rule is a semantic-signal rule that also reaches terminal output, logs, and data viz — not only product UI.)

Signifier Checks

Semantics can flag when a UI signal lies; semiotics and a11y own the deeper checks:

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

For the whole API surface (resources, schemas, pagination, idempotency, versioning, auth, error-envelope design) use api-design; for RFC-level method/status/header/cache detail use http-semantics. Semantics owns whether a specific name, status, field, or error signal tells the truth.

REST Resource Naming

HTTP Status Codes as Semantic Signals

Do not report a failed HTTP request as 200 merely because the transport succeeded. RFC 9110 defines 200 as request success; if the request failed, the status code should carry that failure class. Domain-level partial success can still use a typed success payload when the request itself truly succeeded.

Choosing which code is itself a semantic decision — these distinctions carry meaning consumers act on:

Machine-readable error bodies — RFC 9457 Problem Details

A correct status code tells the client which class of failure occurred; the body should tell it what specifically went wrong, in a structured, predictable shape — not an ad-hoc { "error": "..." } invented per endpoint. RFC 9457 Problem Details for HTTP APIs (July 2023, Standards Track; obsoletes RFC 7807) is the vendor-neutral standard for that body. Media type application/problem+json; the object's reserved members are semantic:

{
  "type": "https://example.com/probs/insufficient-funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Account 12345 has a balance of 30, but the order total is 50.",
  "instance": "/orders/9001"
}

• type — a URI identifying the problem class (stable, dereferenceable, the machine key clients branch on).
• title — short human-readable summary of the problem class (does not change per occurrence).
• status — the HTTP status code, duplicated in-body so it survives proxies/logging; must match the actual response status when present.
• detail / instance — explanation and identifier for this specific occurrence; detail is human-facing and should not be parsed for structured data. Typed extension members carry problem-specific structured data such as validation pointers.

RFC 9457 added (over 7807) explicit guidance for representing multiple problems (e.g. several field-validation errors via an errors extension) and a shared registry of problem types; when different problem types compete, represent the most relevant/urgent one rather than a vague batch envelope. The semantic rule: the status code is the class signal, the type URI is the *ma

…(truncated)