aesthetic-frontend-skills

turn named aesthetics into frontend design direction, CSS custom properties, design tokens, and implementation guidance for AI agents.

Quick install · Choose a skill · Aesthetic examples · Live showcase

What it is

A focused two-skill package for AI agents that need a grounded, repeatable way to move from cultural style language to developer-ready UI decisions. Use it when a product brief says "make this feel like Y2K," "apply dark academia," or "give me usable tokens for a vaporwave interface."

The public package intentionally exposes only two skills:

Scope boundary: this package covers aesthetics. It can flag accessibility, dark-mode, and reduced-motion conflicts, but it does not replace your product accessibility, layout, component architecture, or performance standards.

Aesthetic examples

The website shows how the vocabulary becomes concrete interface direction across very different visual systems.

This package includes 213 canonical aesthetics and 1 compatibility redirect. These are a small sample; browse the full live showcase at aesthetic-design.art/showcase.

These examples are generated components from the package's aesthetic vocabulary. They are illustrative, not a deployment guarantee.

Claymorphism	Decora Kei
Polish Poster School	Harm Reduction Zine
Risograph	Beaux-Arts
Prescription Label Clarity	New Objectivity
XLYK

Outcomes

Agents using these skills should be able to:

1. Resolve a named or loosely described aesthetic to a canonical slug.
2. Describe the aesthetic across palette, type, texture, shape, motion, spatial conventions, and cultural markers.
3. Identify non-negotiable visual signals and anti-patterns that would make the result feel generic.
4. Produce developer-ready design tokens, CSS custom properties, component notes, and implementation guidance.
5. Keep routine app-design work on compact skill-local references instead of loading large research/provenance files.

Which skill should I use?

Example prompts

Use aesthetic-literacy to compare vaporwave and synthwave for a fintech dashboard. Name the better fit and explain the tradeoffs.

Use aesthetic-application to apply dark academia in nostalgic quotation mode to a documentation site. Produce design tokens, CSS custom properties, component notes, and WCAG flags.

The client asked for "cozy retro but not kitsch." Use aesthetic-literacy to disambiguate the likely aesthetics and ask one targeted question before producing a spec.

Apply Web 2.0 Gloss to a pricing page. Keep the output developer-ready: token table, CSS variables, cultural markers, components, and implementation flags.

Quick install

Install both public skills from skills.sh:

npx skills add alexiseverage/aesthetic-frontend-skills

Install them globally for agents that support user-scope skills:

npx skills add alexiseverage/aesthetic-frontend-skills -g

Install one skill at a time:

npx skills add alexiseverage/aesthetic-frontend-skills@aesthetic-literacy
npx skills add alexiseverage/aesthetic-frontend-skills@aesthetic-application

For local development or pre-release validation from a clone, run discovery against the repository root:

npx skills add . -l --full-depth

If your environment already provides the skills binary, the equivalent local command is:

skills add . -l --full-depth

Installed package layout

Installed users primarily need the skill-local files:

• skills/aesthetic-literacy/SKILL.md — trigger rules, 7-dimension framework, disambiguation protocol, and dictionary lookup workflow.
• skills/aesthetic-literacy/references/aesthetic-index.md — generated slug, family, redirect, and alias index.
• skills/aesthetic-literacy/references/aesthetic-manifest.json — generated public machine-readable integration contract for catalog consumers.
• skills/aesthetic-literacy/aesthetics/<slug>.md — compact canonical production guidance for each supported aesthetic.
• skills/aesthetic-application/SKILL.md — application workflow and output requirements.
• skills/aesthetic-application/references/ — output contract, token template, CSS translation patterns, and component-note contract.

Root knowledge/aesthetics/ files are maintainer/provenance resources. They are useful for source review and data maintenance, but they are not the normal hot path for token generation or product design handoffs.

Data model

Each canonical aesthetic entry is designed to be small enough for routine agent use while still carrying enough structure to prevent vague mood-board output.

• Frontmatter identifies slug, label, family, era, aliases, status, evidence_level, related aesthetics, and subsets.
• The body covers the 7-dimension profile: palette, type, texture, shape, motion, spatial conventions, and cultural markers.
• Entries include non-negotiables, connotation guidance, related/subset notes, frontend/UI guidance, CSS translation notes, typography/font guidance, cultural/ethical notes, and anti-patterns.
• Redirect entries point older or superseded terms to the canonical slug.
• scripts/generate_aesthetic_index.py renders both the installed-user Markdown index and the JSON manifest from the same dictionary frontmatter records. python3 scripts/generate_aesthetic_index.py --check verifies both artifacts and fails if either is missing or stale.

Public identity validation normalizes case, whitespace, and punctuation across slugs, labels, and aliases. A name may appear more than once only when every occurrence resolves through redirects to the same canonical entry; collisions across different canonical owners fail validation. Redirect chains must terminate at a canonical entry and cannot contain self-redirects or cycles.

The versioned aesthetic-manifest.json is the public machine-readable integration contract. Its top-level counts and sorted entries expose only stable catalog fields: slug, label, family, status, aliases, and redirect target when applicable. Consumers should use schemaVersion when adapting to future contract changes. Research notes, source logs, and maintainer environment state are intentionally excluded.

See skills/aesthetic-literacy/references/artifact-schema.md for the compact installed-user schema reference.

Validation commands

Contributor validation requires Python 3.10 or newer. The default make check target runs a version preflight and exits with an actionable error before invoking the Python validators or test suite when the interpreter is unsupported. Node.js and npx are also required for the final skills-discovery check.

Run these before opening a release or content PR:

python3 -m pip install -r requirements.txt
make check
npx skills add . -l --full-depth

make check runs:

• make doctor for repository structure and executable-script checks.
• make validate for strict profile and dictionary validation, plus skill metadata, trigger fixtures, generated index, and link validation.
• make audit for strict dictionary/profile consistency and target-schema auditing.
• make generated for Markdown index and JSON manifest freshness.
• make test for the pytest regression suite.

Trigger-selection fixtures live in tests/trigger-evals/. Each public skill listed in skills.sh.json must have one JSON fixture with positive and negative examples.

Maintainer workflow

1. Keep the public skill surface limited to aesthetic-literacy and aesthetic-application unless the project explicitly changes its positioning.

2. Before authoring a canonical entry, load docs/templates/canonical-aesthetic-entry.md and preserve its current frontmatter and section contract. Do not maintain a second copied schema in prompts or contributor notes.

3. Before creating or updating a research profile, load docs/schemas/aesthetic-profile.schema.json; the JSON schema is the source of truth for profile frontmatter.

4. Add or update canonical entries under skills/aesthetic-literacy/aesthetics/ and research profiles under knowledge/aesthetics/.

5. Keep root knowledge/aesthetics/ notes source-grounded and maintainer-focused; do not rely on them for routine installed-user workflows.

6. Regenerate the installed-user index and public JSON manifest after dictionary changes:

   python3 scripts/generate_aesthetic_index.py
   

7. Add or update trigger fixtures in tests/trigger-evals/ when skill descriptions or routing behavior changes.

8. Change schemas, templates, validators, and their regression coverage together in the same PR so authoring guidance cannot drift from enforcement.

9. Run the validation commands above and keep README/CI examples portable. Do not include machine-local paths in docs, generated files, commit messages, or PR text.