| name | heartbeat-design-system |
| description | Apply the Heartbeat design system when building or styling UI: 8pt spacing, limited palette (white, #191919, CTA #FF8C5F), natural easing, structured layouts. Use when the user or project references Heartbeat, this design system, or when implementing interfaces that should follow simplicity, lightness, and ease. |
Heartbeat Design System
Apply this skill when creating or updating UI that must follow the Heartbeat design system. Core principle: design is based on simplicity—lightness, freedom, ease. Use limited styles, intentional spacing, minimal color, and motion with natural easing.
When to Use
- User or project specifies Heartbeat design system
- Building components, pages, or layouts that should feel light and minimal
- Styling CSS/SCSS, Tailwind, or design tokens for this system
Spacing (8pt grid)
Base unit: 8px. Use multiples only: 8, 16, 24, 32, 40, 48, 56, 64, ... (8×n).
Exception: 4px only when strictly necessary.
- Unrelated elements: large separation
- Larger components: larger surrounding space
- White space is structural, not decorative
Examples:
padding: 16px;
margin-bottom: 32px;
gap: 24px;
In Tailwind, prefer: p-4 (16px), gap-6 (24px), mb-8 (32px), etc., and avoid arbitrary values that break the grid.
Color
| Role | Value | Proportion |
|---|
| Primary bg | #FFFFFF | ~80% |
| Primary text | #191919 | ~10% |
| Brand/Black | #191919 | ~10% |
| CTA (actions) | #FF8C5F | ~1% |
- Keep approximate 80/10/10 balance. CTA only for actions; keep it visually distinct.
- No decorative color; do not introduce new colors.
CSS variables example:
--heartbeat-bg: #FFFFFF;
--heartbeat-text: #191919;
--heartbeat-cta: #FF8C5F;
Typography
- Line length: 40–60 characters per line
- Use the project’s predefined font scale; no arbitrary font sizes
- Paragraph spacing: minimum 16px; prefer 24px or 32px
Motion
Default easing: cubic-bezier(0.77, 0, 0.175, 1)
No linear animations. Motion should feel organic: subtle anticipation, smooth deceleration.
transition: all 1s cubic-bezier(0.77, 0, 0.175, 1);
Layout
- Unlimited elements allowed; limited styles enforced
- Structured asymmetry is allowed; spacing can look varied but must follow 8pt logic
- Prioritize breathing space over density; avoid clutter and excessive alignment changes
Illustration (when applicable)
- Background:
#191919
- Small elements:
#FFFFFF with 2px #191919 border
- Text on dark: only on light surfaces. Consistent stroke thickness; no extra color styles.
- Style: “controlled chaos”—precise details, no additional colors.
Green shape (brand element)
Represents speed, proactivity, adaptability. Use as an active, dynamic element in composition or motion; not purely decorative.
Do / Do not
Do:
- Use 8pt spacing grid
- Use only the defined palette
- Use the defined easing curve
- Follow typography scale
- Keep layouts breathing
Do not:
- Add random font sizes
- Add new colors
- Use linear easing
- Overcrowd layouts
- Break the spacing system
Full spec
For the complete developer spec (case study structure, implementation constraints, emotional direction), see reference.md.
