design-md-to-html

name	design-md-to-html
description	Generate a self-contained HTML preview for a DESIGN.md design system. Use when you need to visualize tokens, typography, and components in a functional web page.
license	MIT
metadata	{"author":"albemala","version":"1.0"}

Context

This library serves as the central hub for discovering and publishing Design.md files — AI-readable design systems that ensure UI consistency in design-to-code workflows.

The HTML previews generated by this skill are professional showcases used by developers and designers to evaluate and gain inspiration. Every preview must be a high-quality, functional demonstration that highlights the specific strengths and aesthetic principles of the design system it represents.

DESIGN.md → Self-contained HTML

Use this skill to generate a self-contained *.html preview page for any design-md/**/DESIGN.md design system.

Inputs

1. DESIGN_MD_PATH (required)
   • Example: design-md/african-mobile-first/DESIGN.md
2. OUTPUT_HTML_FILENAME (required)
   • Example: preview.html
3. OUTPUT_DIRECTORY (fixed)
   • The HTML file must be placed in the same directory as the provided DESIGN.md.

Resources

• Design.md Specification

Workflow

1. Analysis

Read the DESIGN.md and extract:

• Tokens: colors, typography (display, h1-h3, body, etc.), rounded (radius), spacing (base, steps, margins).
• Guidelines: Brand style, elevation, shapes, and component behavior rules.

2. Page Concept Selection

Pick a single page type that best represents the design system’s intent.

• Selection criteria: Choose a layout that demonstrates core primitives (CTA buttons, labeled inputs, border-led cards, status badges, intuitive navigation).
• Interaction focus: Show a "bottom sheet" pattern for confirmation flows and a "bottom tab bar" for navigation.

3. Implementation Blueprint

Create a checklist mapping tokens to HTML/CSS/JS:

• Layout: Responsive layout, max-width constraints, page margins.
• Styling: CSS variables for all tokens, typography classes, 48px minimum tap targets.
• Interaction: JS for bottom sheet (open/close/backdrop), blur-based input validation, and tab switching.

4. Code Generation

Generate a single self-contained HTML file with:

• Embedded <style> implementing the tokens.
• Embedded <script> for interactions.
• No external dependencies or build steps (except Google Fonts).
• Typography Integration: You must extract the exact font families and specific font weights defined in the DESIGN.md typography tokens. Ensure that the corresponding fonts are loaded via Google Fonts using the CSS2 API (e.g. <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">). ONLY load the specific font weights that are defined in the design system, avoiding loading unnecessary weights. Fall back to system fonts if the Google Font is unavailable.
• Images: Images from https://images.unsplash.com can be used as placeholders if needed for the design.

Verification Checklist

Before finalizing, ensure:

• All required token values are implemented.
• Layout respects responsive design principles and max-width constraints.
• Tap targets are at least 48px.
• Status communication uses text labels, not just color.
• Input validation happens on blur.
• File is placed next to DESIGN.md.
• Correct typography tokens (font family and weight) are applied.
• Google Fonts are imported correctly, strictly limiting to the utilized font weights.