Component Scaffolding

Generate component skeletons for a Drupal theme using Twig, web components, and Miyagi for validation.

Trigger Phrases

• "Add component skeleton at patterns/..."
• "Create new component..."
• "Scaffold component..."
• Creating/updating schema.yaml or mocks.yaml files

Configuration

Component Library Root

This skill assumes it lives within a component library project, e.g.:

apps/component-library/
├── .claude/
│   └── skills/
│       └── component-scaffolding/   ← this skill
├── src/
│   ├── components/
│   └── css/
└── <theme-name>.libraries.yml

The component library root is three levels up from this skill (i.e., ../../.. relative to this SKILL.md).

Theme Name Discovery

The <theme-name> placeholder must be replaced with the actual Drupal theme name. To determine it:

1. Navigate to the component library root
2. Find the *.libraries.yml file — the filename prefix is the theme name
3. Example: circledot.libraries.yml → theme name is circledot

If the theme name cannot be determined from existing files, ask the user.

File Templates

1. Twig Template: <component-name>.twig

{{ attach_library("<theme-name>/pattern-<component-name>") }}

<div class="<ComponentName>">
	{# Component implementation #}
</div>

• Library name: pattern-<component-name> (kebab-case)
• CSS class: <ComponentName> (PascalCase)
• Single tab indentation

2. CSS: <component-name>.css

/** @define <ComponentName>; */

.<ComponentName > {
  /* Component styles */
}

• PascalCase in @define comment
• Tab indentation

3. JavaScript: <component-name>.js

Only create if explicitly needed. Skip if user says "no JavaScript", "CSS only", etc.

// @ts-check

class <ComponentName> extends HTMLElement {
	constructor() {
		super();
	}

	connectedCallback() {
		this.#addEventListeners();
	}

	/**
	 * Add event listeners
	 */
	#addEventListeners() {
		// Add event listeners here
	}
}

customElements.define("<component-name>", <ComponentName>);

• PascalCase class name
• NO prefix on custom element name (use kebab-case directly)
• Only #addEventListeners() method in skeleton
• NO #elements field or #getElements() method

4. Schema: schema.yaml

$schema: http://json-schema.org/draft-07/schema#
$id: /<tier>/<component-name>

type: object

required:
  - property1

additionalProperties: false
properties:

• $id matches component tier path
• Include required array with placeholder names
• Leave properties: empty in skeleton
• 2-space indentation (YAML standard)

For detailed schema patterns, see [references/schema-and-mocks.md](references/schema-and-mocks.md).

5. Mocks: mocks.yaml

• Single blank line only in skeleton
• User adds their own mock data later

For mock data patterns, see [references/schema-and-mocks.md](references/schema-and-mocks.md).

6. CSS Entry Point: src/css/<component-name>.css

@import url("../components/<tier>/<component-name>/<component-name>.css")
layer(components);

Note: If the component is an element, you can use the elements.css entry point instead.

7. Library Definition: <theme-name>.libraries.yml

Add entry alphabetically within the appropriate tier section:

pattern-<component-name>:
  header: true
  css:
    component:
      build/assets/css/<component-name>.css: {}
  js:
    build/assets/components/<tier>/<component-name>/<component-name>.js:
      attributes:
        type: module

• Omit the js: block entirely if no JavaScript file is created
• Maintain blank line between library definitions
• Omit the css: block entirely if the component is an element

Naming Conventions

Component Tiers

Workflow

1. Create component directory: src/components/<tier>/<component-name>/
2. Create component files (twig, css, schema.yaml, mocks.yaml, and js only if needed)
3. Create CSS entry point: src/css/<component-name>.css
4. Add library definition to <theme-name>.libraries.yml (alphabetically in tier section)
5. Run linters to verify

Optional Files

Pay attention to user requests indicating which files to skip:

Notes

• Skeletons provide structure, not functionality
• All files use tabs except YAML (2 spaces)
• Run linters after creation to verify