AI: Add code formatting guide, update utils guide with indent, add code comment guide to css guide

Author: jlukic

ai/00-START-HERE.md

@@ -89,6 +89,11 @@ Workflows contain required steps (testing, types, exports, documentation) that a
 **Start with:** [Build System Guide](/ai/guides/development/build-system.md)
 **Contains:** Two-system architecture (JS libraries vs web components), build commands reference, esbuild plugins, export conditions, wireit orchestration, common workflows, idiosyncrasies
 
+### Code Formatting & Style
+**Need to:** Understand formatting rules, comment hierarchy, code style conventions
+**Start with:** [Code Formatting Guide](/ai/guides/development/code-formatting.md)
+**Contains:** dprint configuration, three-level comment hierarchy, formatting best practices
+
 ### HTML & CSS Guidelines
 **Need to:** Writing templates, styling components, design tokens, theming
 **Start with:** [HTML Guide](/ai/guides/html/style-guide.md) • [CSS Guide](/ai/guides/css/css-guide.md) • [Theming](/ai/guides/css/theming.md) • [CSS Tokens](/ai/guides/css/tokens/token-usage.md)

ai/guides/css/css-guide.md

@@ -1,12 +1,16 @@
 # Semantic UI CSS Guide
 
-**Purpose**: Canonical patterns for CSS architecture and styling  
+> Last Updated: 2025-11-14
+
+**Purpose**: Canonical patterns for CSS architecture and styling
 **Audience**: All developers building custom components
 
 ## Core Philosophy
 
 Write minimal, maintainable CSS that leverages the design token system and mirrors HTML structure through natural nesting patterns.
 
+> **Code formatting and comment hierarchy**: See `/ai/guides/development/code-formatting.md` for dprint rules and the three-level comment hierarchy for organizing large files.
+
 ## CSS Architecture
 
 ### Nesting Patterns

ai/guides/development/code-formatting.md

@@ -0,0 +1,93 @@
+# Code Formatting Guide
+
+> Last Updated: 2025-11-14
+
+**Purpose**: Code formatting standards and comment hierarchy
+**Audience**: All developers
+
+## Formatting Rules
+
+All code formatting follows `/dprint.json`:
+
+- 2-space indentation (no tabs)
+- 120 character line width
+- Single quotes preferred
+- Always use semicolons
+- Always use braces
+- Sorted imports (case-insensitive)
+- Trailing commas only on multi-line structures
+
+**When in doubt**: Run the formatter or match existing code style.
+
+> **Note**: CSS files are not formatted by dprint. Follow CSS nesting patterns from the CSS guide.
+
+## Comment Hierarchy
+
+For large CSS files, config files, and organized code files, use three-level comment hierarchy:
+
+### Level 1: Major Sections
+
+```css
+/*******************************
+            Groups
+*******************************/
+```
+
+**Use for**: File headers, major functional groups (every 50-100+ lines)
+
+### Level 2: Sub-sections
+
+```css
+/*-------------------
+      Or Buttons
+--------------------*/
+```
+
+**Use for**: Related content within major sections (every 20-50 lines)
+
+### Level 3: Minor Divisions
+
+```css
+/* Types */
+```
+
+**Use for**: Small logical groupings (5-15 lines)
+
+## Comment Guidelines
+
+- **Use title case, not all caps**: `/* Primary Button */` not `/* PRIMARY BUTTON */`
+- **Don't overuse comments** - only where they provide value as breadcrumbs
+- Use simple, concise comments: `/* Remove duplicates from an array */`
+- Consider how Vue, Vite, Svelte use comments - minimal and purposeful
+- Match existing style in the file you're editing
+
+## Application
+
+**CSS Files** (`src/css/`, `src/primitives/*/css/`):
+- Level 1: Theme sections, major groups
+- Level 2: Variations, states, components
+- Level 3: Types, small divisions
+
+**Config Files** (build configurations):
+- Level 1: Configuration domains
+- Level 2: Specific tools, features
+- Level 3: Options, flags
+
+**Large Files** (>200 lines):
+- Level 1: Major functional areas
+- Level 2: Sub-features, groupings
+- Level 3: Implementation details
+
+## Best Practices
+
+✅ **DO:**
+- Use consistent spacing
+- Center-align Level 1 and Level 2 headers
+- Keep headers concise (2-4 words)
+- Match indentation to code
+
+❌ **DON'T:**
+- Mix comment styles in one file
+- Over-use Level 1 headers
+- Skip levels (Level 1 → Level 3)
+- Use for tiny sections (< 5 lines)

ai/meta/context-manifest.json

@@ -74,6 +74,13 @@
       "approxTokens": 26000,
       "description": "Comprehensive guide to Semantic UI's build system: commands, architecture, scripts, plugins, and the two-system design for JS libraries and web components"
     },
+    {
+      "id": "development/code-formatting",
+      "path": "ai/guides/development/code-formatting.md",
+      "category": "specialized",
+      "tags": ["formatting", "code-style", "comments", "dprint"],
+      "approxTokens": 450
+    },
     {
       "id": "html/style-guide",
       "path": "ai/guides/html/style-guide.md",
@@ -95,8 +102,8 @@
       "path": "ai/guides/css/css-guide.md",
       "category": "specialized",
       "tags": ["css", "architecture", "responsive"],
-      "dependsOn": ["html/style-guide"],
-      "approxTokens": 4200
+      "dependsOn": ["html/style-guide", "development/code-formatting"],
+      "approxTokens": 4400
     },
     {
       "id": "css/token-usage",

ai/packages/utils.md

@@ -8,17 +8,18 @@ The `@semantic-ui/utils` package is a comprehensive standalone utility library p
 
 ## Package Structure
 
-The package is organized into **17 specialized modules**, each focused on a specific domain:
+The package is organized into **18 specialized modules**, each focused on a specific domain:
 
 ```
 @semantic-ui/utils
 ├── arrays.js      ← Array manipulation and processing (27+ functions)
-├── objects.js     ← Object operations and property access (15+ functions)  
+├── objects.js     ← Object operations and property access (15+ functions)
 ├── types.js       ← Type checking and validation (15+ functions)
 ├── strings.js     ← String formatting and transformation (8+ functions)
 ├── functions.js   ← Function utilities and higher-order functions
 ├── colors.js      ← OKLCH to RGB/Hex color conversion
 ├── css.js         ← CSS stylesheet adoption, extraction, and scoping
+├── html.js        ← HTML indentation and text formatting
 ├── browser.js     ← Browser-specific operations and XHR
 ├── looping.js     ← Iteration utilities for objects and arrays
 ├── dates.js       ← Date formatting with internationalization
@@ -437,6 +438,94 @@ const rootScoped = scopeStyles(rootCSS, '.app', { appendToRootElements: false })
 // Result: .app html { font-size: 16px; } .app body { margin: 0; }
 ```
 
+## HTML Utilities (html.js)
+
+### Text Indentation
+```javascript
+import { indentLines } from '@semantic-ui/utils';
+
+// Add consistent indentation to all lines
+const code = 'line 1\nline 2\nline 3';
+indentLines(code);              // '  line 1\n  line 2\n  line 3' (2 spaces)
+indentLines(code, 4);           // '    line 1\n    line 2\n    line 3' (4 spaces)
+
+// Useful for template processing
+const template = `
+function example() {
+  return true;
+}
+`;
+const indented = indentLines(template.trim(), 2);
+```
+
+### HTML Indentation
+```javascript
+import { indentHTML } from '@semantic-ui/utils';
+
+// Basic HTML indentation
+const html = '<div>\n<p>Content</p>\n</div>';
+indentHTML(html);
+// Result:
+// <div>
+//   <p>Content</p>
+// </div>
+
+// Handles nested structures
+const nested = `
+<div class="ui segment">
+<div class="ui header">Title</div>
+<p>Content here</p>
+<div class="ui list">
+<div class="item">
+<img src="image.jpg" />
+<div class="content">Item 1</div>
+</div>
+</div>
+</div>
+`;
+
+indentHTML(nested);
+// Result:
+// <div class="ui segment">
+//   <div class="ui header">Title</div>
+//   <p>Content here</p>
+//   <div class="ui list">
+//     <div class="item">
+//       <img src="image.jpg" />
+//       <div class="content">Item 1</div>
+//     </div>
+//   </div>
+// </div>
+
+// Custom indentation
+indentHTML(html, { indent: '    ' });    // 4 spaces
+indentHTML(html, { indent: '\t' });      // Tabs
+
+// Start at specific nesting level
+indentHTML(html, { startLevel: 1 });     // Start with one level of indent
+
+// Preserve empty lines
+indentHTML(html, { trimEmptyLines: false });
+```
+
+**Common use cases:**
+- Cleaning up HTML extracted from JavaScript template literals
+- Formatting documentation examples
+- Processing HTML snippets from various sources
+- Preparing HTML for display in code editors
+
+**Handles correctly:**
+- Void elements (img, br, hr, input, etc.) - no closing tag needed
+- Self-closing syntax (`<component />`)
+- Comments (`<!-- comment -->`)
+- Elements with opening/closing on same line
+- Multiple nesting levels
+
+**Limitations:**
+- Works best with one tag per line (typical documentation format)
+- Multiple tags on same line are not split
+- Designed for well-formed HTML snippets, not error correction
+
 ## Browser Integration (browser.js)
 
 ### Clipboard and Navigation