{"id":51640643,"url":"https://github.com/aipmandy/htmlskill","last_synced_at":"2026-07-13T19:02:15.007Z","repository":{"id":359841464,"uuid":"1247649002","full_name":"AIPMAndy/HTMLskill","owner":"AIPMAndy","description":"Python-first HTML generation framework with design system","archived":false,"fork":false,"pushed_at":"2026-07-06T16:12:41.000Z","size":114,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T18:06:29.532Z","etag":null,"topics":["design-system","html-builder","html-generation","no-build-tools","python","python-framework","wcag-accessibility","web-development"],"latest_commit_sha":null,"homepage":"https://github.com/AIPMAndy/HTMLskill#readme","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AIPMAndy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T15:44:11.000Z","updated_at":"2026-07-06T16:12:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AIPMAndy/HTMLskill","commit_stats":null,"previous_names":["aipmandy/htmlskill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AIPMAndy/HTMLskill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPMAndy%2FHTMLskill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPMAndy%2FHTMLskill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPMAndy%2FHTMLskill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPMAndy%2FHTMLskill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AIPMAndy","download_url":"https://codeload.github.com/AIPMAndy/HTMLskill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPMAndy%2FHTMLskill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35432821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-system","html-builder","html-generation","no-build-tools","python","python-framework","wcag-accessibility","web-development"],"created_at":"2026-07-13T19:02:13.885Z","updated_at":"2026-07-13T19:02:15.001Z","avatar_url":"https://github.com/AIPMAndy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTMLskill\n\n\u003e **Python-first HTML generation framework** — Write Python, get beautiful HTML.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![CI](https://github.com/AIPMAndy/HTMLskill/workflows/CI/badge.svg)](https://github.com/AIPMAndy/HTMLskill/actions)\n[![PyPI version](https://img.shields.io/pypi/v/htmlskill.svg)](https://pypi.org/project/htmlskill/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n**[Live Examples](https://aipmandty.github.io/HTMLskill/)** | **[Documentation](https://github.com/AIPMAndy/HTMLskill/tree/main/docs)** | **[Get Started in 60s](#-quick-start)**\n\n**HTMLskill** combines the simplicity of Python with professional design systems to generate production-ready HTML. No templates, no JSX, no build tools — just Python code that outputs beautiful web pages.\n\n---\n\n## 🎯 Why HTMLskill?\n\n### The Problem with Traditional HTML Generation\n\n| Traditional Approach | HTMLskill |\n|---------------------|-----------|\n| 🤯 Mix Python logic with HTML templates | ✅ Pure Python, no context switching |\n| 🎨 Manual CSS for every element | ✅ Built-in design system (8px grid, WCAG AA) |\n| 📱 Responsive design from scratch | ✅ Mobile-first by default |\n| 🔧 Complex build tools (Webpack, Vite) | ✅ Zero build step, instant output |\n| 🌐 Separate i18n files | ✅ CJK font optimization built-in |\n| 🎭 Multiple template engines | ✅ One API, 9 output modes |\n\n### Real-World Example\n\n**Before (Jinja2 + Manual CSS):**\n```python\n# template.html\n\u003cdiv class=\"hero\" style=\"padding: 64px 24px; background: linear-gradient(...)\"\u003e\n  \u003ch1 style=\"font-size: 48px; font-weight: 700; margin-bottom: 16px;\"\u003e\n    {{ title }}\n  \u003c/h1\u003e\n  \u003cp style=\"font-size: 20px; color: #666; margin-bottom: 32px;\"\u003e\n    {{ description }}\n  \u003c/p\u003e\n  \u003ca href=\"{{ cta_link }}\" style=\"background: #007bff; color: white; ...\"\u003e\n    {{ cta_text }}\n  \u003c/a\u003e\n\u003c/div\u003e\n```\n\n**After (HTMLskill):**\n```python\nimport htmlskill as hs\n\n@hs.page(mode=\"web\", design_system=\"modern\")\ndef landing_page():\n    with hs.hero(gradient=\"blue\"):\n        hs.heading(\"Build Faster with Python\", level=1)\n        hs.text(\"No templates, no build tools, just Python code.\")\n        hs.button(\"Get Started\", href=\"/docs\", variant=\"primary\")\n```\n\n**Result:** Clean Python code → Professional HTML with responsive design, accessibility, and optimized fonts.\n\n---\n\n## ✨ Key Features\n\n### 🐍 Python-First API\n- **Decorator-based**: `@hs.page()` for pages, `@hs.component()` for custom components\n- **Context managers**: `with hs.section():` for nested layouts\n- **Type hints**: Full IDE autocomplete and type checking\n- **Thread-safe**: Use in web frameworks (Flask, FastAPI, Django)\n\n### 🎨 Professional Design System\n- **8px grid system**: Consistent spacing and alignment\n- **WCAG AA compliant**: Accessible color contrast and font sizes\n- **CJK font optimization**: Perfect rendering for Chinese/Japanese/Korean\n- **Responsive by default**: Mobile-first breakpoints (sm, md, lg, xl)\n\n### 🎭 9 Output Modes\nGenerate different HTML structures from the same Python code:\n\n| Mode | Use Case | Output |\n|------|----------|--------|\n| `web` | Landing pages, blogs | Semantic HTML5 |\n| `deck` | Presentations, slides | Fullscreen slides |\n| `poster` | Social media graphics | Fixed-size canvas |\n| `email` | Email campaigns | Table-based layout |\n| `print` | PDF generation | Print-optimized CSS |\n| `app` | Web applications | SPA structure |\n| `doc` | Documentation | Sidebar + content |\n| `story` | Interactive stories | Scroll-driven |\n| `card` | Social cards (OG images) | 1200×630 images |\n\n### 🧩 Rich Component Library\n\n**Basic Components:**\n```python\nhs.heading(\"Title\", level=1)           # H1-H6 with design system\nhs.text(\"Paragraph text\")              # Optimized typography\nhs.button(\"Click me\", variant=\"primary\") # 5 button styles\nhs.image(\"photo.jpg\", alt=\"Photo\")     # Responsive images\nhs.spacer(size=\"lg\")                   # Consistent spacing\nhs.divider()                           # Visual separators\n```\n\n**Layout Components:**\n```python\nwith hs.container(max_width=\"lg\"):     # Centered container\n    with hs.grid(columns=3, gap=\"md\"): # Responsive grid\n        hs.text(\"Column 1\")\n        hs.text(\"Column 2\")\n        hs.text(\"Column 3\")\n```\n\n**Composite Components:**\n```python\nwith hs.hero(gradient=\"purple\"):       # Hero section\n    hs.heading(\"Welcome\")\n    hs.button(\"Get Started\")\n\nwith hs.features(columns=3):           # Feature grid\n    hs.feature(icon=\"⚡\", title=\"Fast\", description=\"...\")\n    hs.feature(icon=\"🎨\", title=\"Beautiful\", description=\"...\")\n```\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\npip install htmlskill\n```\n\n### 60-Second Tutorial\n\nCreate `my_page.py`:\n\n```python\nimport htmlskill as hs\n\n@hs.page(mode=\"web\", design_system=\"modern\")\ndef my_landing_page():\n    # Hero section\n    with hs.hero(gradient=\"blue\"):\n        hs.heading(\"Build Faster with Python\", level=1)\n        hs.text(\"No templates, no build tools, just Python code.\")\n        hs.button(\"Get Started\", href=\"/docs\", variant=\"primary\")\n    \n    # Features section\n    with hs.section(padding=\"xl\"):\n        hs.heading(\"Why HTMLskill?\", level=2, align=\"center\")\n        with hs.features(columns=3):\n            hs.feature(\n                icon=\"🐍\",\n                title=\"Python-First\",\n                description=\"Write Python, get HTML. No context switching.\"\n            )\n            hs.feature(\n                icon=\"🎨\",\n                title=\"Design System\",\n                description=\"Professional design out of the box.\"\n            )\n            hs.feature(\n                icon=\"⚡\",\n                title=\"Zero Build\",\n                description=\"No Webpack, no Vite, just Python.\"\n            )\n\n# Render to HTML\nhtml = my_landing_page()\nprint(html)\n```\n\n**2. Save to file:**\n\n```python\nwith open(\"index.html\", \"w\") as f:\n    f.write(html)\n```\n\n**3. Or use the CLI:**\n\n```bash\nhtmlskill render my_page.py --output index.html\n```\n\n---\n\n## 📚 Use Cases\n\n### 1. Landing Pages\n```python\n@hs.page(mode=\"web\", design_system=\"startup\")\ndef product_landing():\n    with hs.hero(gradient=\"purple\"):\n        hs.heading(\"Your Product Name\")\n        hs.text(\"One-line value proposition\")\n        hs.button(\"Start Free Trial\", variant=\"primary\")\n    \n    with hs.features(columns=3):\n        # Add features...\n    \n    with hs.cta(background=\"dark\"):\n        hs.heading(\"Ready to get started?\")\n        hs.button(\"Sign Up Now\", variant=\"accent\")\n```\n\n### 2. Presentation Decks\n```python\n@hs.page(mode=\"deck\", design_system=\"minimal\")\ndef my_presentation():\n    with hs.slide(background=\"white\"):\n        hs.heading(\"Slide Title\", level=1, align=\"center\")\n        hs.text(\"Slide content\", align=\"center\")\n    \n    with hs.slide(background=\"gradient-blue\"):\n        hs.heading(\"Next Slide\")\n        with hs.grid(columns=2):\n            hs.text(\"Left column\")\n            hs.text(\"Right column\")\n```\n\n### 3. Email Campaigns\n```python\n@hs.page(mode=\"email\", design_system=\"email-safe\")\ndef newsletter():\n    with hs.container(max_width=\"600px\"):\n        hs.heading(\"Weekly Newsletter\")\n        hs.text(\"This week's highlights...\")\n        hs.button(\"Read More\", href=\"https://example.com\")\n```\n\n### 4. Social Media Cards\n```python\n@hs.page(mode=\"card\", design_system=\"social\")\ndef og_image():\n    with hs.card(size=\"1200x630\"):\n        hs.heading(\"Blog Post Title\", level=1)\n        hs.text(\"Author Name\")\n        hs.image(\"logo.png\", position=\"bottom-right\")\n```\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Your Python Code                      │\n│                  @hs.page(mode=\"web\")                    │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│                  HTMLskill API Layer                     │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │\n│  │  Decorators  │  │   Context    │  │  Registry    │  │\n│  │  @page       │  │  Management  │  │  Components  │  │\n│  │  @component  │  │  Thread-safe │  │  Validation  │  │\n│  └──────────────┘  └──────────────┘  └──────────────┘  │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│                  Component Library                       │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │\n│  │    Basic     │  │    Layout    │  │  Composite   │  │\n│  │  heading()   │  │ container()  │  │   hero()     │  │\n│  │  text()      │  │   grid()     │  │ features()   │  │\n│  │  button()    │  │  section()   │  │   cta()      │  │\n│  └──────────────┘  └──────────────┘  └──────────────┘  │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│                  Design System Layer                     │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │\n│  │  Typography  │  │    Colors    │  │   Spacing    │  │\n│  │  Font sizes  │  │  Palettes    │  │   8px grid   │  │\n│  │  Line height │  │  Contrast    │  │  Responsive  │  │\n│  └──────────────┘  └──────────────┘  └──────────────┘  │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│                  Template Renderer                       │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │\n│  │     Web      │  │     Deck     │  │    Email     │  │\n│  │  Semantic    │  │  Fullscreen  │  │  Table-based │  │\n│  │    HTML5     │  │    Slides    │  │    Layout    │  │\n│  └──────────────┘  └──────────────┘  └──────────────┘  │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n              ┌───────────────┐\n              │  HTML Output  │\n              │  + Inline CSS │\n              └───────────────┘\n```\n\n---\n\n## 🆚 Comparison with Alternatives\n\n| Feature | HTMLskill | Jinja2 | Django Templates | React |\n|---------|-----------|--------|------------------|-------|\n| **Language** | Pure Python | Python + HTML | Python + HTML | JavaScript |\n| **Learning Curve** | ⭐ Low | ⭐⭐ Medium | ⭐⭐ Medium | ⭐⭐⭐ High |\n| **Design System** | ✅ Built-in | ❌ Manual | ❌ Manual | ⚠️ Requires library |\n| **Build Tools** | ✅ None | ✅ None | ✅ None | ❌ Required |\n| **Type Safety** | ✅ Full | ⚠️ Partial | ⚠️ Partial | ✅ With TypeScript |\n| **Responsive** | ✅ Default | ❌ Manual | ❌ Manual | ⚠️ Requires CSS |\n| **Accessibility** | ✅ WCAG AA | ❌ Manual | ❌ Manual | ⚠️ Manual |\n| **Output Modes** | ✅ 9 modes | ❌ 1 mode | ❌ 1 mode | ❌ 1 mode |\n| **Server-Side** | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ SSR complex |\n\n**When to use HTMLskill:**\n- ✅ You prefer Python over JavaScript\n- ✅ You need professional design without hiring a designer\n- ✅ You want multiple output formats (web, deck, email, etc.)\n- ✅ You value type safety and IDE autocomplete\n- ✅ You want zero build tools and instant output\n\n**When to use alternatives:**\n- ❌ You need a full SPA with client-side routing (use React)\n- ❌ You already have a large Jinja2/Django template codebase\n- ❌ You need pixel-perfect custom design (use Tailwind CSS)\n\n---\n\n## 🛣️ Roadmap\n\n### Phase 1: Core API (Current - Alpha)\n- [x] Basic components (heading, text, button, image)\n- [x] Layout components (container, grid, section)\n- [x] Composite components (hero, features, cta)\n- [x] Design system (8px grid, WCAG AA, CJK fonts)\n- [x] Web template renderer\n- [ ] CLI tool (`htmlskill render`, `htmlskill watch`)\n- [ ] Documentation site\n\n### Phase 2: Advanced Features (Q2 2026)\n- [ ] Deck template (presentation slides)\n- [ ] Email template (campaign-ready)\n- [ ] Card template (social media OG images)\n- [ ] Form components (input, select, checkbox)\n- [ ] Navigation components (navbar, sidebar, breadcrumb)\n- [ ] Animation support (fade, slide, zoom)\n- [ ] Dark mode support\n\n### Phase 3: Ecosystem (Q3 2026)\n- [ ] Plugin system for custom components\n- [ ] Integration with Flask/FastAPI/Django\n- [ ] VS Code extension (syntax highlighting, snippets)\n- [ ] Component marketplace\n- [ ] Figma → HTMLskill converter\n- [ ] AI-powered component generation\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Quick Start for Contributors:**\n\n1. **Fork and clone:**\n   ```bash\n   git clone https://github.com/YOUR_USERNAME/HTMLskill.git\n   cd HTMLskill\n   ```\n\n2. **Install dev dependencies:**\n   ```bash\n   pip install -e \".[dev]\"\n   ```\n\n3. **Run tests:**\n   ```bash\n   pytest tests/ -v\n   ```\n\n4. **Follow TDD:**\n   - Write tests first (RED)\n   - Implement feature (GREEN)\n   - Refactor code (REFACTOR)\n\n5. **Submit PR:**\n   - Create a feature branch\n   - Add tests for new features\n   - Update documentation\n   - Submit pull request\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **Mesop API**: Inspiration for the decorator-based API\n- **huashu-design**: Design system principles\n- **html-anything**: Multi-template rendering approach\n\n---\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/AIPMAndy/HTMLskill/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/AIPMAndy/HTMLskill/discussions)\n- **Email**: [Your Email]\n\n---\n\n**Built with ❤️ by the HTMLskill team**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faipmandy%2Fhtmlskill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faipmandy%2Fhtmlskill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faipmandy%2Fhtmlskill/lists"}