@markuplint/html-spec 4.16.1 → 4.17.0

package/README.md

@@ -16,8 +16,6 @@ This package serves as the data layer in markuplint's specification system, depe
 
 ## Package Architecture
 
-This package serves as the data layer in markuplint's specification system:
-
 ```
 @markuplint/ml-spec (Foundation Layer)
   ↓ provides types, algorithms, schemas
@@ -34,69 +32,17 @@ Core packages (Application Layer)
 ### Generated Output (DO NOT EDIT)
 
 - **`index.json`** - Consolidated specification data (48K+ lines)
-  - All HTML elements with complete specifications
-  - Global attribute definitions (`#HTMLGlobalAttrs`, `#ARIAAttrs`)
-  - ARIA role and property definitions (`#aria`)
-  - Content model macros (`#contentModels`)
-  - Citation references to authoritative sources
 
 ### Source Files (EDIT THESE)
 
-- **`src/spec-*.json`** - Individual element specifications
-  - `src/spec.div.json` → `<div>` element specification
-  - `src/spec.table.json` → `<table>` element specification
-  - `src/spec.svg_text.json` → `<svg:text>` element specification
-- **`src/spec-common.attributes.json`** - Shared attribute definitions
-- **`src/spec-common.contents.json`** - Reusable content model macros
+- **`src/spec.*.json`** - Individual element specifications (177 files)
+- **`src/spec-common.attributes.json`** - Global attribute category definitions (19 categories)
+- **`src/spec-common.contents.json`** - Content model category macros (HTML 10 + SVG 19 categories)
 
-### Build Process
+### Build System
 
 - **`build.mjs`** - Generation script that invokes `@markuplint/spec-generator`
-- **External data sources**:
-  - **MDN Web Docs** - Element descriptions, compatibility data, attribute metadata
-  - **W3C ARIA specifications** - Role definitions, property mappings (1.1/1.2/1.3)
-  - **HTML Living Standard** - Obsolete element definitions
-  - **SVG specifications** - SVG element definitions and categories
-
-## Data Structure
-
-The generated `index.json` follows this structure:
-
-```typescript
-{
-  cites: Cites;           // Reference citations to external specs
-  def: {                  // Global definitions
-    "#HTMLGlobalAttrs": GlobalAttributes;
-    "#ARIAAttrs": ARIAAttributes;
-    "#aria": ARIASpecification;
-    "#contentModels": ContentModelMacros;
-  };
-  specs: ElementSpec[];   // Individual element specifications
-}
-```
-
-### Element Specification Format
-
-Each element specification includes:
-
-```typescript
-{
-  name: string;                    // Element name (e.g., "table", "tr")
-  cite: string;                   // MDN reference URL
-  description: string;            // Human-readable description
-  categories: string[];           // Content categories (flow, phrasing, etc.)
-  contentModel: ContentModel;     // Permitted child elements
-  globalAttrs: GlobalAttrSets;    // Applicable global attributes
-  attributes: AttributeSpecs;     // Element-specific attributes
-  aria: {                        // ARIA integration
-    implicitRole: string | null;  // Default ARIA role
-    permittedRoles: string[] | boolean;  // Allowed ARIA roles
-    namingProhibited?: boolean;   // Accessible name constraints
-    conditions?: ConditionalARIA; // Context-specific ARIA rules
-  };
-  omission?: TagOmissionRules;    // Start/end tag omission rules
-}
-```
+- Fetches live data from MDN, W3C ARIA specs, and HTML Living Standard
 
 ## Relationship to @markuplint/ml-spec
 
@@ -105,190 +51,12 @@ Each element specification includes:
 - **Type definitions** (`ElementSpec`, `ExtendedSpec`, `MLMLSpec`) that structure this data
 - **JSON schemas** that validate the specification format
 - **Algorithms** that process and compute values from this specification data
-- **Runtime utilities** that consume this consolidated specification data
 
 **@markuplint/html-spec** (this package) provides:
 
 - **Canonical HTML data** following the type definitions from `@markuplint/ml-spec`
 - **External data enrichment** from MDN and W3C specifications
 - **Build automation** that keeps data synchronized with external sources
-- **Single consolidated dataset** optimized for runtime consumption
-
-This separation enables:
-
-- **Independent data updates** without affecting type definitions or algorithms
-- **Algorithm improvements** without requiring data regeneration
-- **Framework extensions** that can augment this base HTML data
-
-## Development Workflow
-
-### Adding or Editing HTML Elements
-
-1. **Edit source specifications**
-   - Add new file: `src/spec.<element>.json` (e.g., `src/spec.dialog.json`)
-   - Edit existing: Update relevant `src/spec-*.json` file
-   - For SVG elements: Use pattern `src/spec.svg_<local>.json`
-
-2. **Regenerate the dataset**
-
-   ```bash
-   # From repository root (recommended)
-   yarn up:gen
-
-   # Or for this package only
-   yarn workspace @markuplint/html-spec run gen
-   ```
-
-3. **Verify output**
-   - Check `index.json` for expected changes
-   - Ensure no unintended modifications to other elements
-
-### Element Specification Guide
-
-**Minimal element specification**:
-
-```json
-{
-  "contentModel": {
-    "contents": [{ "require": "#phrasing" }]
-  },
-  "globalAttrs": {
-    "#HTMLGlobalAttrs": true,
-    "#ARIAAttrs": true
-  },
-  "attributes": {
-    "custom-attr": { "type": "String" }
-  },
-  "aria": {
-    "implicitRole": "button",
-    "permittedRoles": ["link", "tab"]
-  }
-}
-```
-
-**Key principles**:
-
-- Only specify what differs from defaults or overrides MDN data
-- Use references to global attribute sets when possible
-- Define content models using semantic categories (`#flow`, `#phrasing`)
-- Include ARIA specifications following HTML-ARIA mapping guidelines
-
-### Common Editing Patterns
-
-**Adding element-specific attributes**:
-
-```json
-{
-  "attributes": {
-    "href": {
-      "type": "URL",
-      "required": false,
-      "description": "Target URL for navigation"
-    },
-    "download": {
-      "type": "String",
-      "experimental": true
-    }
-  }
-}
-```
-
-**Conditional ARIA rules**:
-
-```json
-{
-  "aria": {
-    "implicitRole": "link",
-    "permittedRoles": ["button", "menuitem"],
-    "conditions": {
-      ":not([href])": {
-        "implicitRole": "generic",
-        "namingProhibited": true
-      }
-    }
-  }
-}
-```
-
-**Complex content models**:
-
-```json
-{
-  "contentModel": {
-    "contents": [{ "transparent": ":not(:model(interactive), a, [tabindex])" }]
-  }
-}
-```
-
-## Build Process Details
-
-### What `yarn up:gen` does
-
-1. **Invokes spec-generator** with inputs:
-   - HTML spec sources: `src/spec-*.json`
-   - Common attributes: `src/spec-common.attributes.json`
-   - Common content models: `src/spec-common.contents.json`
-
-2. **External data enrichment**:
-   - **MDN scraping**: Fetches descriptions, categories, attribute metadata
-   - **ARIA integration**: Downloads W3C ARIA specifications (1.1/1.2/1.3)
-   - **Obsolete elements**: Adds deprecated elements from HTML Living Standard
-   - **SVG specifications**: Includes SVG element definitions and categories
-
-3. **Data consolidation**:
-   - Merges manual specifications with fetched data
-   - Resolves conflicts (manual data takes precedence)
-   - Validates against JSON schemas from `@markuplint/ml-spec`
-   - Generates citations and references
-
-4. **Output generation**:
-   - Writes consolidated `index.json`
-   - Formats with Prettier
-   - Validates structural integrity
-
-### External Data Sources
-
-**MDN Web Docs** (`developer.mozilla.org`):
-
-- Element descriptions and usage guidance
-- Compatibility tables and browser support
-- Attribute metadata (deprecated, experimental, obsolete)
-- Tag omission rules and semantic information
-
-**W3C ARIA Specifications**:
-
-- **ARIA 1.1**: `https://www.w3.org/TR/wai-aria-1.1/`
-- **ARIA 1.2**: `https://www.w3.org/TR/wai-aria-1.2/`
-- **ARIA 1.3**: `https://w3c.github.io/aria/`
-- **HTML-ARIA**: `https://www.w3.org/TR/html-aria/`
-
-**HTML Living Standard** (`https://html.spec.whatwg.org/`):
-
-- Obsolete element definitions
-- Semantic category classifications
-- Content model specifications
-
-### Caching and Performance
-
-- **External fetches are cached** to prevent unnecessary network requests during development
-- **CI/CD builds** refresh external data to stay current with specification changes
-- **Generated output is optimized** for runtime consumption (single file, pre-resolved references)
-
-## File Naming Conventions
-
-**HTML elements**: `src/spec.<tag>.json`
-
-- Examples: `spec.div.json`, `spec.table.json`, `spec.input.json`
-
-**SVG elements**: `src/spec.svg_<local>.json`
-
-- Examples: `spec.svg_text.json`, `spec.svg_circle.json`
-- Element name inferred as `svg:<local>` (e.g., `svg:text`)
-
-**Special files**:
-
-- `spec-common.attributes.json` - Global attribute category definitions
-- `spec-common.contents.json` - Reusable content model macros
 
 ## Install
 
@@ -305,30 +73,14 @@ $ yarn add @markuplint/html-spec
 
 </details>
 
-## Important Notes
-
-### Do Not Edit Generated Files
-
-- **Never modify `index.json` directly** - it will be overwritten
-- Always update source files in `src/` and regenerate
-
-### Manual Data Takes Precedence
-
-- Your specifications in `src/spec-*.json` override scraped MDN data
-- Use this to correct inaccuracies or add missing information
-- External data fills gaps but doesn't override manual specifications
-
-### Specification Compliance
-
-- ARIA mappings should follow W3C HTML-ARIA mapping guidelines
-- Content models should align with HTML Living Standard definitions
-- Attribute types should reference `@markuplint/types` definitions
+## Contributing
 
-### Framework Integration
+For detailed documentation, see:
 
-- This package provides base HTML specifications
-- Framework-specific packages (Vue, React, Svelte) extend this base data
-- Extensions are merged at runtime using `@markuplint/ml-spec` utilities
+- [Architecture](ARCHITECTURE.md) -- Package structure, data flow, and integration points
+- [Element Specification Format](docs/element-spec-format.md) -- JSON spec file reference, content models, ARIA integration
+- [Build Pipeline](docs/build-pipeline.md) -- Build process, external data sources, spec-generator modules
+- [Maintenance Guide](docs/maintenance.md) -- Common recipes, testing, troubleshooting
 
 ## License
 

package/SKILL.md

@@ -0,0 +1,358 @@
+---
+description: Perform maintenance tasks for @markuplint/html-spec
+---
+
+# html-spec-maintenance
+
+Perform maintenance tasks for `@markuplint/html-spec`: regenerate specification data,
+review upstream changes, update manual spec files, and ensure cross-package consistency.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                                  | Description                                            |
+| ------------------------------------- | ------------------------------------------------------ |
+| `update`                              | Regenerate `index.json` and review upstream changes    |
+| `add-element <name>`                  | Add a new HTML element specification                   |
+| `add-svg-element <name>`              | Add a new SVG element specification                    |
+| `add-attribute <element> <attr>`      | Add an attribute to an element                         |
+| `remove-attribute <element> <attr>`   | Remove an attribute from an element                    |
+| `obsolete-element <name>`             | Mark an element as obsolete                            |
+| `obsolete-attribute <element> <attr>` | Mark an attribute as deprecated                        |
+| `change-flag <element> <attr> <flag>` | Change `experimental`/`deprecated`/`nonStandard` flags |
+| `check`                               | Verify cross-package consistency                       |
+
+If omitted, defaults to `update`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `docs/element-spec-format.md` -- JSON spec file format reference
+- `docs/build-pipeline.md` -- Build pipeline and data precedence rules
+
+## Task: update
+
+The primary maintenance workflow. Regenerate `index.json` with the latest MDN/W3C data
+and review what has changed.
+
+### Step 1: Regenerate
+
+```bash
+yarn up:gen
+```
+
+This runs `@markuplint/spec-generator`, which scrapes live MDN data and merges it with
+the manual spec files in `src/`. The result is written to `index.json`.
+
+### Step 2: Review the diff
+
+```bash
+git diff packages/@markuplint/html-spec/index.json
+```
+
+Categorize each change:
+
+| Category                        | Examples                                                           | Action                                                                                                                    |
+| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| **Minor description rewording** | MDN refines role/element/attribute descriptions                    | Commit as-is                                                                                                              |
+| **New attributes**              | `interestfor`, `switch` added by MDN                               | Commit as-is (MDN-sourced, no manual spec change needed)                                                                  |
+| **Flag transitions**            | `experimental` → `deprecated`, `nonStandard` added/removed         | Commit as-is                                                                                                              |
+| **Significant spec changes**    | ARIA property `required` → `inherited`, content model restructured | Requires manual spec update (go to Step 3)                                                                                |
+| **ARIA 1.3 updates**            | New/revised role definitions, property requirement changes         | WAI-ARIA 1.3 is a Working Draft -- expect ongoing changes. 1.1 and 1.2 are finalized Recommendations and will not change. |
+
+> **Caution -- ARIA version duplication:** `index.json` contains role definitions for
+> WAI-ARIA 1.1, 1.2, and 1.3, so many strings appear three times. When editing
+> descriptions or properties, **do not use `replace_all`** -- it will modify all three
+> versions simultaneously. Always target the specific version block you intend to change.
+
+### Step 3: Handle significant changes (if any)
+
+If the diff contains substantive changes to element behavior, ARIA mappings, or
+content models:
+
+1. Identify the affected elements
+2. Determine which source files need updating:
+   - `src/spec.<element>.json` for element-specific changes
+   - `src/spec-common.contents.json` for content model category changes
+   - `src/spec-common.attributes.json` for global attribute changes
+   - In rare cases, `@markuplint/ml-spec` schemas or types may need updating
+3. Make the changes, referencing the authoritative specification:
+   - HTML Living Standard: https://html.spec.whatwg.org/multipage/
+   - HTML-ARIA: https://w3c.github.io/html-aria/
+   - WAI-ARIA: https://w3c.github.io/aria/
+4. Regenerate to incorporate manual spec changes:
+   ```bash
+   yarn up:gen
+   ```
+5. Verify the final diff is correct
+
+### Step 3b: Idempotency verification (when spec files are modified)
+
+When you modify `src/spec.*.json` files, verify that your changes produce stable output
+before committing. This ensures the generated `index.json` does not contain unintended
+drift:
+
+```bash
+# 1. Stage spec files and index.json
+git add packages/@markuplint/html-spec/src/spec.*.json packages/@markuplint/html-spec/index.json
+
+# 2. Regenerate
+yarn up:gen
+
+# 3. Check that the attributes you changed are NOT in the diff (= stable output)
+git diff packages/@markuplint/html-spec/index.json | grep '"your-attr"'
+
+# 4. If stable, discard the regenerated file and use the staged version
+git checkout packages/@markuplint/html-spec/index.json
+
+# 5. Proceed to commit
+```
+
+If the diff shows unexpected changes for your attribute, it means the spec file and
+the generator produce different values -- investigate before committing.
+
+### Step 4: Test and commit
+
+```bash
+yarn workspace @markuplint/html-spec run test
+```
+
+Stage and commit `index.json` and any modified `src/` files.
+
+## Task: add-element
+
+Add a new HTML element specification. Follow recipe #1 in `docs/maintenance.md`.
+
+1. Read `src/spec.a.json` as a reference for a typical element
+2. Create `src/spec.<name>.json` with required fields:
+   - `contentModel` with `contents`
+   - `globalAttrs` (`#HTMLGlobalAttrs`, `#GlobalEventAttrs`, `#ARIAAttrs` set to `true`)
+   - `attributes` (element-specific, can be `{}`)
+   - `aria` with `implicitRole` and `permittedRoles`
+3. Add spec URL comments at the top (`//` format)
+4. **Cross-package step**: If the element belongs to content categories (flow, phrasing, etc.),
+   add it to the appropriate categories in `src/spec-common.contents.json`.
+   Without this, `@markuplint/rules`' `permitted-contents` rule will flag the element
+   as invalid content in parent elements that allow those categories.
+5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+6. Verify the element appears in `index.json`
+7. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: add-svg-element
+
+Add a new SVG element specification. Follow recipe #3 in `docs/maintenance.md`.
+
+1. Read `src/spec.svg_circle.json` as a reference for a typical SVG element
+2. Create `src/spec.svg_<name>.json` (the `svg_` prefix maps to namespace `svg:<name>`)
+3. Use SVG-specific global attribute categories (`#SVGCoreAttrs`, `#SVGPresentationAttrs`)
+4. For ARIA, use AAM references: `{ "core-aam": true, "graphics-aam": true }`
+5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: add-attribute
+
+Add an attribute to an element. Follow recipe #2 in `docs/maintenance.md`.
+
+1. Open `src/spec.<element>.json`
+2. Add the attribute entry to the `attributes` object. See `docs/element-spec-format.md`
+   for the full attribute definition format. Common patterns:
+   - Simple typed attribute: `"href": { "type": "URL" }`
+   - Conditional attribute: `"accept": { "type": ..., "condition": "[type='file' i]" }`
+   - Boolean attribute: `"disabled": { "type": "Boolean" }`
+3. For a **global** attribute (applies to all elements), edit
+   `src/spec-common.attributes.json` instead, adding the attribute to the
+   appropriate category (e.g., `#HTMLGlobalAttrs`)
+4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+5. Verify the attribute appears in `index.json` with correct metadata
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: remove-attribute
+
+Remove an attribute from an element's manual specification.
+
+1. Open `src/spec.<element>.json`
+2. Remove the attribute entry from the `attributes` object
+3. For a **global** attribute, edit `src/spec-common.attributes.json` instead
+4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+5. Verify the attribute no longer appears in `index.json` for the element.
+   **Note**: If the attribute also exists in MDN data, it will still appear in
+   `index.json` from the MDN source. To fully suppress an MDN-sourced attribute,
+   you may need to override it in the manual spec rather than simply removing it.
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: obsolete-element
+
+Mark an element as obsolete. Follow recipe #8 in `docs/maintenance.md`.
+
+There are two approaches:
+
+- **Via spec-generator's hardcoded list** (preferred for standard obsolete elements):
+  Add the element name to the `obsoleteList` array in
+  `packages/@markuplint/spec-generator/src/html-elements.ts`
+- **Via manual spec file**: Set `"obsolete": true` in the element's
+  `src/spec.<element>.json`
+
+Obsolete elements automatically get:
+
+- `cite` pointing to the HTML spec obsolete features section
+- `contents: true` (any content allowed)
+- `permittedRoles: true`, `implicitRole: false`
+
+After making the change:
+
+1. Regenerate: `yarn up:gen`
+2. Verify the element appears in `index.json` with `"obsolete": true`
+3. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: obsolete-attribute
+
+Mark an attribute as deprecated in an element's specification.
+
+1. Open `src/spec.<element>.json`
+2. Add `"deprecated": true` to the attribute definition:
+   ```json
+   "align": {
+     "deprecated": true
+   }
+   ```
+   If the attribute already has other fields (`type`, `condition`, etc.),
+   simply add `"deprecated": true` alongside them.
+3. For a **global** attribute, edit `src/spec-common.attributes.json` instead
+4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+5. Verify the attribute shows `"deprecated": true` in `index.json`
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: change-flag
+
+Change the `experimental`, `deprecated`, or `nonStandard` flag on an attribute.
+
+These boolean flags indicate the standardization status of an attribute:
+
+| Flag           | Meaning                                                           |
+| -------------- | ----------------------------------------------------------------- |
+| `experimental` | The attribute is part of an emerging specification not yet stable |
+| `deprecated`   | The attribute is obsolete and should not be used                  |
+| `nonStandard`  | The attribute is not part of any standard                         |
+
+1. Open `src/spec.<element>.json` (or `src/spec-common.attributes.json` for globals)
+2. Add, change, or remove the flag on the target attribute:
+   ```json
+   "attributionsrc": {
+     "deprecated": true
+   }
+   ```
+   To remove a flag, delete the property entirely.
+3. **Note**: Flags from MDN scraping also appear in `index.json`. Manual spec flags
+   take precedence, so setting a flag in the manual spec will override the MDN value.
+   However, MDN-only attributes (not defined in manual specs) can only be overridden
+   by adding an entry for that attribute in the manual spec.
+4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
+5. Verify the flag change in `index.json`
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## ARIA Version System
+
+### Resolution Logic
+
+`resolveVersion()` (`@markuplint/ml-spec/src/utils/resolve-version.ts`) checks
+`aria[version]` first, falls back to top-level `aria`. The runtime default is
+`ARIA_RECOMMENDED_VERSION = '1.2'` (`@markuplint/ml-spec/src/utils/aria-version.ts`).
+
+### Key Placement Rules
+
+| Key              | Meaning                                                   | Mutability                                   |
+| ---------------- | --------------------------------------------------------- | -------------------------------------------- |
+| Top-level `aria` | Default / latest. Fallback for versions without overrides | Mutable — update to match current W3C Rec    |
+| `"1.1"`          | ARIA 1.1 snapshot                                         | **Frozen** — never add new roles             |
+| `"1.2"`          | ARIA 1.2 snapshot (rarely needed)                         | Only create when top-level diverges from 1.2 |
+
+### Decision: Where to add new permittedRoles
+
+1. Is the role in the W3C Recommendation "ARIA in HTML" (ARIA 1.2 based, Aug 2025)?
+   → Add to **top-level only**
+2. Is the role ARIA 1.3 draft-only (not in W3C Rec)?
+   → Add to **top-level**, AND create `"1.2"` key with the current 1.2 list to freeze it
+3. Was the role in the original ARIA 1.1 spec for this element?
+   → It should already be in `"1.1"`. **Never add new roles to `"1.1"`**.
+
+### permittedRoles Quick Reference
+
+| Pattern                                  | Meaning                             |
+| ---------------------------------------- | ----------------------------------- |
+| `true`                                   | Any role allowed                    |
+| `false`                                  | No roles allowed                    |
+| `["role1", "role2"]`                     | Specific roles (alphabetical order) |
+| `[{"name": "role", "deprecated": true}]` | Deprecated role                     |
+
+## Task: check
+
+Verify cross-package consistency between `@markuplint/html-spec` and related packages.
+
+1. **Content model categories**: Verify that category names in `src/spec-common.contents.json`
+   match the `Category` enum in `@markuplint/ml-spec/schemas/content-models.schema.json`
+2. **Element membership**: Verify that elements listed in content categories have
+   corresponding `src/spec.<element>.json` files and consistent `contentModel` definitions
+3. **Attribute types**: Check that attribute type references (e.g., `"URL"`, `"<color>"`)
+   exist in `@markuplint/types`' definitions registry
+4. **Schema validation**: Run `yarn workspace @markuplint/html-spec run test` to validate
+   all source JSON files against `@markuplint/ml-spec` schemas
+
+Report results as:
+
+```
+| # | Check | Status | Notes |
+```
+
+## Testing Requirements for Spec Changes
+
+Spec data changes propagate to multiple test suites. Always run `yarn test`
+(full suite) before committing.
+
+### Test Matrix
+
+| Change type                         | Primary test file                            | Also check                                                    |
+| ----------------------------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| ARIA (implicitRole, permittedRoles) | `rules/src/wai-aria/index.spec.ts`           | `ml-spec/src/algorithm/aria/get-permitted-roles-spec.spec.ts` |
+| Attributes (new/changed)            | `rules/src/invalid-attr/index.spec.ts`       | Existing tests with changed enum error messages               |
+| Content model                       | `rules/src/permitted-contents/index.spec.ts` | —                                                             |
+
+### Cross-Package Impact
+
+- **Hardcoded role arrays**: `ml-spec/.../get-permitted-roles-spec.spec.ts` has
+  hardcoded `permittedRoles` for img, button, input, form, etc. Update these
+  when changing `permittedRoles` in html-spec.
+- **Enum error messages**: Adding a value to an enum (e.g., button `command`)
+  changes the error message string in existing `invalid-attr` tests.
+
+### Test Conventions
+
+- `toStrictEqual` with exact `{ severity, line, col, message, raw }` — never `toBeGreaterThan(0)`
+- Always include both valid (empty violations) and invalid (exact violation) cases
+- ARIA version in tests: `{ rule: { options: { version: '1.1' } } }`
+- Some roles require ARIA attributes: focusable `separator` → `aria-valuenow`,
+  `meter` → `aria-valuenow`
+
+## Rules
+
+1. **`index.json` is generated -- never edit it directly.** Always modify `src/` files and regenerate.
+2. **Manual spec data takes precedence over MDN data.** Attributes defined in `src/spec.*.json` override same-named MDN-sourced attributes. Use this to correct inaccurate MDN data.
+3. **Minor MDN description changes should be committed as-is.** Do not attempt to override cosmetic upstream improvements.
+4. **Content model category membership is critical.** A missing element in a category causes `permitted-contents` rule false positives in downstream linting.
+5. **Always run tests after changes.** Schema validation catches structural errors before they propagate to downstream packages.
+6. **Reference authoritative specs for significant changes.** Use WebSearch to verify against HTML Living Standard, WAI-ARIA, and HTML-ARIA before modifying manual spec files.
+7. **Use conventional commit prefixes based on the nature of the change:**
+
+   | Change type              | Prefix  | Example                                           |
+   | ------------------------ | ------- | ------------------------------------------------- |
+   | Description updates only | `chore` | `chore(html-spec): update role descriptions`      |
+   | Attribute/spec additions | `feat`  | `feat(html-spec): add input switch attribute`     |
+   | Spec data corrections    | `fix`   | `fix(html-spec): correct ARIA mapping for button` |
+
+8. **Separate spec changes into individual PRs.** Each specification change (new attribute, ARIA mapping fix, etc.) should be on its own branch and PR. Description-only updates can be batched into a single PR.
+9. **Run `yarn test` (full suite) before committing.** Spec changes affect `@markuplint/rules` and `@markuplint/ml-spec` tests.
+10. **Keep `permittedRoles` arrays in alphabetical order.**