@n8d/htwoo-patterns

Pattern library for the hTWOo design system. This package contains exported Handlebars templates, data files, and images from htwoo-core for use in Pattern Lab projects.

Overview

This package provides:

• Pattern Templates (.hbs) - Handlebars templates for all hTWOo components
• Pattern Data (.json) - Sample data and configuration for patterns
• Pattern Documentation (.md) - Documentation for each pattern
• Images - All required image assets
• Automatic Installation - Patterns are automatically copied to your Pattern Lab project on install

Installation

npm install @n8d/htwoo-patterns

Automatic Pattern Installation

When you install this package, the postinstall script automatically copies patterns to your Pattern Lab project:

1. Detects your Pattern Lab configuration (patternlab-config.json)
2. Copies _patterns/ to your configured source directory
3. Copies _data/ to your configured source directory
4. Copies images/ to your configured source directory

Note: This requires a Pattern Lab project with a valid patternlab-config.json file.

Package Contents

@n8d/htwoo-patterns/
├── _patterns/          # Pattern templates organized by atomic design
│   ├── atoms/
│   ├── molecules/
│   ├── organisms/
│   ├── templates/
│   └── pages/
├── _data/              # Pattern data files
├── images/             # Image assets
├── lib/                # Installation scripts
│   └── move-patterns.js
└── manifest.json       # File tracking manifest (auto-generated)

Usage in Pattern Lab

After installation, patterns are available in your Pattern Lab project:

{{> atoms-button }}
{{> molecules-card }}
{{> organisms-header }}

Refer to the hTWOo documentation for detailed pattern usage.

Toggling Pattern Visibility

Control which patterns are visible in Pattern Lab by toggling the hidden property:

# Toggle visibility for all patterns (true <-> false)
npx htwoo-toggle-patterns toggle

# Hide all patterns (set hidden: true)
npx htwoo-toggle-patterns hide

# Show all patterns (set hidden: false)
npx htwoo-toggle-patterns show

# Preview changes without modifying files
npx htwoo-toggle-patterns toggle --dry-run
npx htwoo-toggle-patterns hide --dry-run --verbose

This modifies the YAML frontmatter in your Pattern Lab's _patterns/**/*.md files. The hidden property controls visibility in the Pattern Lab interface.

Development Workflow

This package uses @n8d/htwoo-pattern-export to manage pattern synchronization from htwoo-core.

Available Scripts

Pattern Export

# Export patterns from htwoo-core to this package
npm run export

# Export with verbose output
npm run export:verbose

# Preview changes without modifying files
npm run export:dry-run

# Compare current patterns with htwoo-core (same as export:verbose)
npm run compare

Pattern Visibility Control

Toggle the hidden property in YAML frontmatter of all .md files:

# Toggle hidden property (false -> true, true -> false)
npm run toggle-hidden
npm run toggle-hidden:dry-run  # Preview changes

# Hide all patterns (set hidden: true)
npm run hide-all
npm run hide-all:dry-run       # Preview changes

# Show all patterns (set hidden: false)
npm run show-all
npm run show-all:dry-run       # Preview changes

These commands modify the YAML frontmatter in all markdown files:

• Adds hidden: true or hidden: false to the frontmatter
• Creates frontmatter if it doesn't exist
• Useful for controlling pattern visibility in Pattern Lab

Exporting Patterns

When developing hTWOo patterns in htwoo-core, use the export script to update this package:

cd packages/htwoo-patterns
npm run export:dry-run  # Preview changes first
npm run export          # Apply changes

The export process:

1. Compares files between htwoo-core/src/ and this package
2. Uses MD5 hashes to detect changed files
3. Copies only modified, new, or removed patterns
4. Updates manifest.json to track changes
5. Generates a report of changes

Comparing Patterns

To check if your local patterns are in sync with htwoo-core:

npm run compare

This shows:

• Modified files - Patterns that changed in htwoo-core
• New files - Patterns added to htwoo-core
• Removed files - Patterns deleted from htwoo-core

Package Maintainers

Building the Package

This package is maintained as part of the hTWOo monorepo. To update patterns:

1. Make changes in htwoo-core

   cd htwoo-core
   # Edit patterns in src/_patterns/

2. Export to htwoo-patterns

   cd packages/htwoo-patterns
   npm run export:verbose

3. Review changes

   • Check the export report
   • Verify manifest.json was updated
   • Test patterns in a Pattern Lab project

4. Commit and publish

   git add .
   git commit -m "chore: Update patterns from htwoo-core"
   npm version patch  # or minor/major
   npm publish

Manifest Tracking

The manifest.json file tracks MD5 hashes of all exported files:

{
  "version": "1.0.0",
  "timestamp": "2025-11-29T...",
  "files": {
    "_patterns/atoms/button/button.hbs": "abc123...",
    "_data/colors.json": "def456...",
    "images/logo.svg": "ghi789..."
  }
}

Important: manifest.json is excluded from git (via .gitignore) but included in the npm package. This allows:

• Clean git history (no manifest changes on every pattern update during development)
• Accurate comparison when users install the package
• Users can compare their installed version with the latest htwoo-core

Related Packages

• @n8d/htwoo-core - Core CSS framework and pattern source
• @n8d/htwoo-pattern-export - Pattern export and comparison tool

Links

• Documentation
• GitHub Repository
• npm Package
• Issue Tracker

License

MIT - See LICENSE file for details

Support

• GitHub Sponsors - Stefan Bauer
• GitHub Sponsors - n8design