Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@n8d/htwoo-patterns) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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:

Detects your Pattern Lab configuration (patternlab-config.json)
Copies _patterns/ to your configured source directory
Copies _data/ to your configured source directory
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:

Compares files between htwoo-core/src/ and this package
Uses MD5 hashes to detect changed files
Copies only modified, new, or removed patterns
Updates manifest.json to track changes
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:

Make changes in htwoo-core

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

Export to htwoo-patterns

cd packages/htwoo-patterns
npm run export:verbose

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

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

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

License

MIT - See LICENSE file for details

JSPM