DOCSEARCHbyAlgolia
Submit Docs

Hallmark Design Skill

repository·main·Indexed 10 days ago

https://github.com/nutlope/hallmark

A design skill for AI coding assistants (Claude Code, Cursor, Codex) that generates high-quality, non-generic UIs. Powered by Together AI, it uses macrostructures, themes, and a 57-gate slop test to avoid common LLM patterns. Features include a CLI with verbs for auditing, redesigning, and studying design DNA, as well as a custom theme route for unique brand identities.

Tokens
149.3K
Snippets
236
Records
525
Agent score
98%

What's inside Hallmark

  1. Overview of the Hum theme

    main

    The Hum theme is a playful, vibrant, and "alive" design register. It is characterized by cream paper backgrounds, a multi-accent palette, rounded sans typography, and generous radii. It is intended for products that are non-serious, such as daily-curiosity apps, learning platforms, habit trackers, and kids' tools.

    Key Characteristics:

    • Paper: Light, warm cream tinted toward pear-yellow (~95°).
    • Typography: Rounded sans (Plus Jakarta Sans / Open Runde) with no serifs allowed.
    • Accents: Multi-accent (Pear-yellow, Sky-cyan, and Coral-red) used simultaneously on different surfaces.
    • Motion: Mandatory hover-and-on-paint motion with soft lifting shadows.

  2. Overview of the Carnival theme

    main

    The Carnival theme is a loud-maximalist editorial style characterized by a duo-tone accent system, chunky variable display typography, decorative ornaments, hard-offset shadows, and tinted paper. It is designed to feel decorative rather than raw, making it suitable for brands with high character like independent music labels, zine collectives, or indie game studios.

    Key Visual Axes:

    • Paper band: Light, tinted background (varies by palette drop).
    • Display style: Display-heavy using Big Shoulders Display 800 with variable-width axis.
    • Accent hue: Per-drop duo-tone pairs (e.g., warm+warm, cool+warm).

    This theme is loaded eagerly by SKILL.md Step 3 when the catalog pick is carnival. The default palette and font stack are defined in site/css/tokens.css under the [data-theme="carnival"] selector.

  3. Overview of the Cobalt theme

    main
    Cobalt is a modern-minimal, 'dev-tool register' theme designed for API, SDK, CLI, documentation, or developer platform landing pages. It follows the 'GitBook / Firecrawl / Vercel' aesthetic: a calm, cool-white engineered canvas with ruler-drawn hairlines, a single electric cobalt signal accent, and code as the primary hero element. It is intended to feel like a precise, fast instrument panel rather than a marketing template.

  4. Understand Hallmark's export formats and output rules

    main

    Hallmark automatically emits design system tokens in four canonical formats during every build.

    1. tokens.css: The primary source of truth. This file is always written to the project root and contains plain CSS custom properties at :root.
    2. Tailwind v4 @theme: For Tailwind projects. This is provided inline within the design.md file's Exports section.
    3. DTCG tokens.json: For token pipelines (e.g., Style Dictionary, Token Studio, Cobalt). This is provided inline within design.md.
    4. shadcn/ui CSS variables: For shadcn/ui projects. This is provided inline within design.md.

    Note: You do not need to run a specific command to generate these; they are a side effect of the build process. To use the non-CSS formats, copy the relevant block from design.md into your project.

  5. Understand the Hallmark verbs

    main

    Hallmark provides three primary verbs for generation testing, each designed for a specific transformation or analysis task. These verbs operate on different input types and produce distinct outputs:

    • audit: Analyzes an input (e.g., an AI-templated landing fragment) against a list of anti-patterns. It returns a ranked punch list of issues but does not edit the original content.
    • redesign: Takes an existing page structure (e.g., a centered hero, 3 cards, CTA, and footer) and rebuilds it using a different structural fingerprint. It preserves the original copy and Information Architecture (IA).
    • study: Extracts the 'DNA' from a description or screenshot (e.g., macrostructure, archetypes, type-pairing, and accents). It returns a diagnosis report and then rebuilds user content using that extracted DNA. It never copies pixels.

    Input and Output Formats

    VerbInput TypeOutput Type
    auditHTML fragmentMarkdown report
    redesignHTML pageindex.html + style.css
    studyMarkdown description or screenshotMarkdown report

  6. Review Hallmark generation test findings

    main

    Hallmark's generation tests (v0.5.0) evaluate the skill's ability to produce structurally diverse web pages based on different briefs. Key success metrics include:

    • Structural Variety: Producing distinct macrostructures, hero archetypes, and footer voices for different briefs.
    • Enrichment Restraint: Correctly choosing when not to add visual enrichment (e.g., typography-only for podcasts or manifestos).
    • Enrichment Hierarchy: Selecting appropriate enrichment tiers (e.g., hand-built CSS art instead of Lottie/video files).
    • Context Inference: Using inferred-context disclosure sentences at the top of brief.md when context is skipped.
    • Type Pairing: Maintaining consistent font stacks driven by theme logic.
    • CSS Art: Using pure CSS for complex visual elements (like trace waterfalls or clipped-edge mockups) rather than external assets.

  7. Understand the `hallmark study` verb and its purpose

    main
    The hallmark study command is used to extract the DNA of a design from a reference source (either a screenshot or a URL). Instead of copying pixels or creating a visual façade, study produces a diagnosis report that describes the design's macrostructure, component archetypes, type-pairing, color anchors, and rhythm. This report allows you to apply those design principles to your own content without creating a direct copy of the source.

  8. Core Principles of Microinteractions

    main

    Microinteractions in Hallmark follow a specific mental model: trigger → rules → feedback → loops/modes. To avoid 'slop' (unintentional or decorative motion), follow these principles:

    • Intentional Motion: Every animation must clarify, guide, or confirm. If it is purely decorative, remove it.
    • Silent Success: Do not use toasts for successful actions if the user can already see the result. Reserve toasts for failures or actions with hidden effects.
    • Optimistic UI: Update the UI immediately on user action and process the request in the background. If the request fails, animate a rollback and provide an 'Undo' option.
    • Reduced Motion: Treat prefers-reduced-motion as a first-class state. For reduced motion, collapse spatial motion to opacity crossfades, keep duration $\le$ 150ms, and preserve functional state changes.
    • Accessibility: Every hover affordance must have a keyboard focus equivalent. No interaction should be hover-only.

  9. Follow Hero Animation Discipline

    main

    The hero is a high-stakes animation surface. Follow these constraints to maintain professional quality:

    The Golden Rule

    One orchestrated reveal per page. The hero should settle in 0.4–0.8s with a single coordinated motion, then stop. Avoid 'scroll-fade-everything' patterns.

    Banned Animations

    • Bouncy elastic easing (e.g., cubic-bezier(0.34, 1.56, ...)).
    • Parallax-on-mouse or mouse-follow gradients (unless for portfolio/creative/agency work).
    • Particle/starfield backgrounds.
    • Auto-rotating carousels (unless WCAG 2.2.2 compliant with pause controls).

    Allowed Animations

    • Single image-fade-in-late (approx. 0.6s after headline lands, with 0.4s duration).
    • Type-unmask on headlines using clip-path.
    • View Transitions API for state changes.
    • Number-ticking for stat-led heroes ($\le$ 1.2s).
    • A single subtle Lottie or CSS loop ($\le$ 4s).

    Accessibility

    Reduced-motion is mandatory. Every animation must include a @media (prefers-reduced-motion: reduce) block that either disables the motion or replaces it with a static keyframe.

  10. Reference Hallmark's token taxonomy (Source of Truth)

    main

    All Hallmark outputs are translations of a core set of tokens. If you introduce new tokens to a page, you must name them by role and add them to tokens.css. Do not invent new names downstream that do not exist in the tokens.css source of truth.

    Common token categories include:

    • Colours: --color-paper, --color-ink, --color-accent, etc.
    • Fonts: --font-display, --font-body, --font-outlier.
    • Spacing: --space-3xs through --space-5xl (4-pt scale).
    • Typography: --text-xs through --text-display (major-third ratio scale).
    • Easing: --ease-out, --ease-in, --ease-in-out.
    • Duration: --dur-micro, --dur-short, --dur-long.
    • Other: --rule-hair, --rule-fine, --radius-card, --shadow-card.

  11. Avoid the Specimen-fall-through anti-pattern

    main

    When using Hallmark, do not treat recipes as fixed templates. Duplicating a recipe verbatim to achieve identical results is considered the Specimen-fall-through anti-pattern (gate 23 in SKILL.md).

    Hallmark is designed for structural variety. Even when using the same recipe (e.g., Recipe 00 · Coffeebox) on the same project, the engine should produce different macrostructures or themes across consecutive runs. This behavior is enforced by the project memory stored in .hallmark/log.json.

  12. Techniques for hand-built CSS/SVG illustration

    main

    To achieve a high-quality, hand-built aesthetic in 2026, follow these four core habits:

    1. Use @property for declarative interpolation: Animating typed custom properties (<length>, <number>, <angle>, <color>) enables GPU-composited animation without JavaScript.
    2. Apply asymmetric transform: rotate(): Avoid perfect symmetry, which reads as algorithmic. Use small, controlled rotations (e.g., ±1°) to create a hand-drawn feel.
    3. Layer opacity for detail: Use varying opacity levels (e.g., 0.6 for veins or secondary labels) to establish a hierarchy of attention.
    4. Ground decorative work with mono labels: Use monospace fonts (var(--font-mono)) for technical sub-labels to ensure decorative elements remain legible and functional.