@maccesar/titools 2.10.0 → 2.10.1

package/lib/commands/update.js

@@ -30,6 +30,7 @@ import { formatList, isTitaniumProject } from '../utils.js';
 import { getAgentsSkillsDir } from '../config.js';
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
+import os from 'os';
 
 /**
  * Check if a platform has any skill symlinks installed
@@ -105,7 +106,9 @@ export async function updateCommand(options) {
   if (!options.local) {
     const projectDir = process.cwd();
     const isProject = isTitaniumProject(projectDir);
-    const hasLocalSkills = isProject && hasSkillsAt(projectDir);
+    // When cwd === home, "local" and "global" point to the same .agents/skills dir
+    const isHomeDir = projectDir === os.homedir();
+    const hasLocalSkills = !isHomeDir && isProject && hasSkillsAt(projectDir);
     const hasGlobalSkills = hasSkillsAt(undefined);
 
     // Only show prompt if BOTH local and global skills exist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/SKILL.md

@@ -112,6 +112,18 @@ purgetss create 'MyApp' -d -v fa
 # -v: Copy icon fonts (fa, mi, ms, f7)
 ```
 
+## What's New in v7.9.0
+
+- Opacity modifier on semantic colors — `bg-surface/65` syntax now works for any class mapped through `theme.extend.colors`. PurgeTSS auto-derives `<originalKey>_<alphaPercent>` entries in `semantic.colors.json` per mode (light/dark). See [Semantic Colors → Opacity modifier auto-derivation](references/semantic-colors.md#opacity-modifier-auto-derivation). **Native rebuild required** — Liveview hot-reload alone does not refresh `semantic.colors.json`
+- `theme.Window` / `theme.View` / `theme.ImageView` presets now use **replace mode** — they no longer carry framework defaults (white background, `Ti.UI.SIZE`, iOS `hires: true`). This fixes gradient ghosting where a preset Window with `bg-gradient-*` apply was being covered by the implicit `backgroundColor: '#FFFFFF'`. Use `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` when you want **extend mode** (merge with defaults). See [Apply Directive → Extend mode vs replace mode](references/apply-directive.md#extend-mode-vs-replace-mode)
+- Glossary path renamed: `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`
+
+## What's New in v7.8.0
+
+- `purgetss images --width <n>` — pin SVG output to a specific base width; PurgeTSS derives per-density assets from the multiplier scale (×1 / ×1.5 / ×2 / ×3 / ×4). Range `[1, 8192]`. CLI-only (no `images:` config equivalent — width is per-asset). See [Multi-Density Images → Pinning the output width with --width](references/multi-density-images.md#pinning-the-output-width-with---width)
+- Class syntax pre-validation — the build now emits a `Class Syntax Error` block (file path + line + `Fix:` suggestion) for 5 detected patterns: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace inside parens (`wh-( 200 )` → `wh-(200)`), redundant `px` unit (`top-(10px)` → `top-(10)`). See [Arbitrary Values → Class syntax pre-validation](references/arbitrary-values.md#class-syntax-pre-validation)
+- Parser fix for negative values inside parentheses — `top-(-10)` is now correctly flagged as inverted-negative-sign instead of silently misparsed
+
 ## What's New in v7.7.0
 
 - `brand:` config restructured — flat keys replaced by purpose-based groups: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`

package/skills/purgetss/references/animation-advanced.md

@@ -238,15 +238,6 @@ const { saveComponent } = require('purgetss.ui')
 saveComponent({ source: $.myView, directory: 'screenshots' })
 ```
 
-### createAnimation(args)
-
-Factory function to create Animation objects programmatically.
-
-```javascript
-const { createAnimation } = require('purgetss.ui')
-const anim = createAnimation({ duration: 300, curve: Ti.UI.ANIMATION_CURVE_EASE_IN_OUT })
-```
-
 ---
 
 ## Implementation Rules

package/skills/purgetss/references/app-branding.md

@@ -301,6 +301,16 @@ brand: {
 >
 > Generating `splash_icon.png` does not automatically switch Titanium to use it for the Android 12+ system splash. Titanium still needs a custom splash theme that points `android:windowSplashScreenAnimatedIcon` to `@drawable/splash_icon`. If you do nothing, Android keeps using `ic_launcher`.
 
+> **WARNING**
+>
+> Merge splash settings into the existing Android theme
+> If your app already has a custom Android theme block in `tiapp.xml`, **merge** the new splash settings (the `android:windowSplashScreenAnimatedIcon` entry and any sibling theme attributes) into that existing theme. Do **not** append a second `<application>` element or a duplicate theme block — Titanium will only honor one theme definition, and the duplicate silently shadows or overrides the original, leading to "my settings were ignored" debugging sessions. Always edit the existing `<application>` / theme block in place.
+
+> **INFO**
+>
+> A brief flash on splash exit is usually the system, not your PNGs
+> If you still see a brief flash or abrupt exit transition during splash dismissal even with correct assets in place, **do not assume the PNGs PurgeTSS generates are wrong**. That artifact commonly comes from Android 12+'s system splash exit transition (or from Titanium's splash theme handoff to your first window), not from the splash icon files themselves. Regenerating `splash_icon.png` will not change it — the fix lives in the splash theme animation, not in the icon assets.
+
 ## Android legacy splash fallback
 
 Since v7.7.0, PurgeTSS regenerates `app/assets/android/default.png` in Alloy projects and `Resources/android/default.png` in Classic projects.
@@ -411,6 +421,16 @@ purgetss brand --cleanup-legacy --aggressive
 > Commit first
 > `--cleanup-legacy` deletes files permanently. Commit your project to git before running without `--dry-run` so `git restore` is available as a rollback.
 
+> **INFO**
+>
+> Files kept on purpose
+> `--cleanup-legacy` intentionally does **not** remove the following files, even when modern adaptive launcher icons and splash assets are already in place:
+>
+> - `app/assets/android/default.png` (Alloy projects)
+> - `Resources/android/default.png` (Classic projects)
+>
+> These remain because they are still required by Titanium framework defaults — older Android splash code paths fall back to `default.png`, and removing it can cause build warnings or a missing-asset error on certain Titanium SDK versions even when modern splash assets exist. Treat them as part of the baseline asset set, not as legacy clutter.
+
 ## Troubleshooting
 
 ### The icon looks cropped or cramped on my phone

package/skills/purgetss/references/appearance-module.md

@@ -2,15 +2,71 @@
 
 The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every controller in the app reads and writes the same state.
 
-This file covers the four public methods, the required setup, a full Settings-view example, and the lifecycle that keeps the saved mode in sync with the UI. For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
+This reference follows the same workflow-first / API-second split the official PurgeTSS documentation now uses:
+
+- **Workflow** — initialize at startup, then build a Settings view that calls `Appearance.set(...)` (mirrors `best-practices/1-appearance-setup.md`).
+- **API reference** — the four public methods, exact signatures, and lifecycle (mirrors `purgetss-ui/10-appearance.md`).
+
+For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
 
 > **INFO**
 >
 > Requires PurgeTSS **>= 7.5.3**. On older versions the `Appearance` export does not exist — the `require('purgetss.ui')` call will succeed, but `Appearance` will be `undefined`. Run `purgetss --version` in the project root to confirm.
 
-## Setup
+## How it fits together
+
+The Appearance module sits between three moving parts: a JS singleton, the OS-level interface style, and the semantic colors generated by PurgeTSS. The diagram below shows how a single `Appearance.init()` call at startup wires them together, and what happens when the user later picks a mode in Settings.
+
+```
+┌─ app/lib/appearance.js (singleton from purgetss.ui) ─────────────────┐
+│                                                                      │
+│   Appearance.init()  ────► reads 'userInterfaceStyle'                │
+│                            from Ti.App.Properties                    │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.set(m)  ────► writes Ti.App.Properties                  │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.get()   ────► returns 'system' | 'light' | 'dark'       │
+│   Appearance.toggle()────► flips between 'light' and 'dark'          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Ti.UI.semanticColorType (runtime) ──────────────────────────────────┐
+│                                                                      │
+│   Light mode  ─►  resolves bg-surface       to surfaceColor.light    │
+│                   resolves text-on-surface  to textColor.light       │
+│                                                                      │
+│   Dark mode   ─►  resolves bg-surface       to surfaceColor.dark     │
+│                   resolves text-on-surface  to textColor.dark        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Utility classes in views ───────────────────────────────────────────┐
+│                                                                      │
+│   bg-surface, text-on-surface, bg-border, bg-surface-high, ...       │
+│   Repaint instantly on every Appearance.set(...) call.               │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
+
+## Workflow
+
+The fastest path from zero to a working Light / Dark toggle is three steps. Each one maps to one section of the official `best-practices/1-appearance-setup.md` guide.
 
-Call `Appearance.init()` **once** at app startup, before opening the first window. The standard place is the top of `app/controllers/index.js`.
+### 1. Define semantic colors
+
+Create `app/assets/semantic.colors.json` and register the color names under `theme.extend.colors` in `purgetss/config.cjs`. The class names you use in XML (`bg-surface`, `text-on-surface`, `bg-border`, ...) come from this mapping.
+
+See [semantic-colors.md](./semantic-colors.md) for the JSON schema, the `config.cjs` mapping, nesting rules, and alpha transparency.
+
+### 2. Initialize Appearance at startup
+
+Call `Appearance.init()` **once** before opening the first window. The standard place is the top of `app/controllers/index.js`:
 
 `app/controllers/index.js`
 ```js
@@ -27,22 +83,11 @@ $.navWin.open()
 >
 > Call `Appearance.init()` **before** `$.navWin.open()` (or whichever window you open first). If the window opens first, it will render once against the system default and then flicker to the saved mode when `init()` runs — a visible flash on cold launch.
 
-## Methods
-
-| Method       | Description                                                                 |
-| ------------ | --------------------------------------------------------------------------- |
-| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
-| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
-| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
-| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
-
-All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
-
-## Full Settings-view example
+### 3. Build an Appearance toggle
 
-A three-row settings panel — System / Light / Dark — where each row shows a `fa-solid fa-circle-check` icon next to the currently active mode. Tapping a row calls `Appearance.set(...)` and updates the check icons.
+Build a Settings view where users pick `System`, `Light`, or `Dark`. Tapping a row calls `Appearance.set(...)` and updates the check icons.
 
-### View
+#### View
 
 `app/views/settings.xml`
 ```xml
@@ -86,7 +131,7 @@ A three-row settings panel — System / Light / Dark — where each row shows a
 </Alloy>
 ```
 
-### Controller
+#### Controller
 
 `app/controllers/settings.js`
 ```js
@@ -95,16 +140,16 @@ const { Appearance } = require('purgetss.ui')
 // Sync check icons with the mode saved at app startup.
 updateUI(Appearance.get())
 
-const selectDark   = () => selectAppearance('dark')
-const selectLight  = () => selectAppearance('light')
-const selectSystem = () => selectAppearance('system')
+function selectDark()   { selectAppearance('dark') }
+function selectLight()  { selectAppearance('light') }
+function selectSystem() { selectAppearance('system') }
 
-const selectAppearance = (value) => {
+function selectAppearance(value) {
   Appearance.set(value)
   updateUI(value)
 }
 
-const updateUI = (value) => {
+function updateUI(value) {
   $.themeDarkCheck.visible   = (value === 'dark')
   $.themeLightCheck.visible  = (value === 'light')
   $.themeSystemCheck.visible = (value === 'system')
@@ -113,9 +158,24 @@ const updateUI = (value) => {
 
 The background, text, border, and icon colors in the XML come from semantic color classes (`bg-surface`, `bg-surface-high`, `text-on-surface`, `bg-border`, etc.) — see [semantic-colors.md](./semantic-colors.md) for how to wire those up so the whole view flips when `Appearance.set('dark')` fires.
 
-## Lifecycle
+> **Why named functions in Alloy controllers?** Alloy resolves `onClick="selectDark"` by looking up a top-level identifier on the controller scope. Named function declarations (`function selectDark() { ... }`) hoist and are reliably resolvable; arrow functions assigned to `const` are not hoisted and tend to bite you when an XML attribute fires before the binding has executed. The official setup guide uses named functions for this reason.
 
-How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate:
+## API reference
+
+### Methods
+
+| Method       | Description                                                                 |
+| ------------ | --------------------------------------------------------------------------- |
+| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
+| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
+| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
+| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
+
+All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
+
+### Lifecycle
+
+How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate during a typical session:
 
 ```
 app startup
@@ -143,8 +203,6 @@ app startup
           +-- Preference survives the next cold launch
 ```
 
-`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
-
 > **INFO**
 >
 > `toggle()` intentionally skips `'system'`. If the current mode is `'system'`, calling `toggle()` produces `'dark'`. If you want a three-way cycle (System -> Light -> Dark -> System), build it in userland with `Appearance.get()` + `Appearance.set(...)`; do not expect `toggle()` to do it.

package/skills/purgetss/references/apply-directive.md

@@ -254,6 +254,66 @@ Window: { default: { apply: 'exit-on-close-false bg-blue-500' } }
 
 Use the explicit `default:` wrapper when you also need platform blocks (`ios:`, `android:`) next to it. For the common case of one bundle of defaults, the shorthand reads better.
 
+### Extend mode vs replace mode
+
+> **HEADLINE CHANGE — v7.9.0**
+> This is the headline change of PurgeTSS v7.9.0. Before v7.9.0, `theme.Window` / `theme.View` / `theme.ImageView` still had the framework defaults merged in, which caused gradient ghosting and other surprising overrides. v7.9.0 makes top-level (non-`extend`) configs behave as true replace mode.
+>
+> If you previously used `theme.Window` (no `extend`) and depended on the white background or the iOS `hires: true` / `Ti.UI.SIZE` defaults still being there, you will need to either move that config under `theme.extend.Window` (extend mode) or add the previously-implicit utilities back into your `apply` string.
+
+PurgeTSS follows the Tailwind convention for the three Ti Elements that ship with framework defaults — `Window`, `View`, and `ImageView`:
+
+- **Extend mode** — `theme.extend.Window`, `theme.extend.View`, `theme.extend.ImageView`. Your customization **merges** with the framework defaults. The white Window `backgroundColor`, `Ti.UI.SIZE` width/height on `View`, and iOS `hires: true` on `ImageView` stay in place unless you override them with `apply`. Use this when you want to add to the defaults, not replace them.
+- **Replace mode** — `theme.Window`, `theme.View`, `theme.ImageView` (top level, no `extend`). Your config **replaces** the framework defaults entirely. The white Window background is omitted, the `Ti.UI.SIZE` width/height on `View` is omitted, and the iOS `hires: true` on `ImageView` is omitted. Your `apply` becomes the source of truth for that Ti Element.
+
+Use replace mode when you want full control and do not want a preset mixed in. The canonical case is a Window declared at `theme.Window` with a `backgroundGradient`, where the previously-merged white `backgroundColor` would render on top of the gradient and produce a "ghost" white wash.
+
+`./purgetss/config.cjs - replace mode (v7.9.0+)`
+```javascript
+module.exports = {
+  theme: {
+    Window: {
+      apply: 'bg-gradient-to-b from-blue-500 to-purple-600'
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+'Window': { backgroundGradient: { type: 'linear', colors: [...], startPoint: ..., endPoint: ... } }
+```
+
+Note the missing `backgroundColor: '#FFFFFF'`. Replace mode skipped the framework default, so the gradient renders cleanly. Before v7.9.0 the same config produced:
+
+```tss
+/* Pre-v7.9.0 — ghost white background covering the gradient */
+'Window': { backgroundColor: '#FFFFFF', backgroundGradient: { type: 'linear', colors: [...] } }
+```
+
+If you wanted the framework white background **and** something else on top, that is what extend mode is for:
+
+`./purgetss/config.cjs - extend mode`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      Window: {
+        apply: 'exit-on-close-false'
+      }
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+/* Framework default backgroundColor is preserved, exitOnClose merged in */
+'Window': { backgroundColor: '#FFFFFF', exitOnClose: false }
+```
+
+The same extend-vs-replace distinction applies to `View` (`Ti.UI.SIZE` width/height defaults) and `ImageView` (iOS `hires: true` default).
+
 ### Apply Wins Over Static Defaults
 
 If `apply` sets a property that the component already has as a built-in default, the applied value replaces the original instead of both ending up in the final TSS:

package/skills/purgetss/references/arbitrary-values.md

@@ -7,6 +7,47 @@ When you need a one-off value that is not in the defaults, use arbitrary values
 >
 > You cannot use square bracket notation like in Tailwind because Titanium handles platform and conditional statements in `.tss` files differently.
 
+## Class syntax pre-validation
+
+Starting with PurgeTSS v7.8.0, the build runs a pre-validation pass over class names found in XML views and JS controllers before purging. When it spots a malformed arbitrary-value utility, it stops and prints a structured `Class Syntax Error` block so the offending class can be fixed before any TSS is generated. If multiple errors are present, all of them are reported in the same run.
+
+Each error block includes:
+
+- The file path where the offending class lives
+- The line number inside that file
+- The offending class name (as authored)
+- A `Fix:` suggestion with the corrected class name
+
+Example shape:
+
+```
+Class Syntax Error
+  File: app/views/index.xml
+  Line: 12
+  Found: top-(-10)
+  Fix:   -top-(10)
+```
+
+### Detected patterns
+
+The validator catches five narrow, actionable mistakes:
+
+| Pattern                       | Offending input | Suggested fix | Notes                                                            |
+| ----------------------------- | --------------- | ------------- | ---------------------------------------------------------------- |
+| Inverted negative sign        | `top-(-10)`     | `-top-(10)`   | The `-` prefix goes before the rule, not inside the value        |
+| Tailwind-style brackets       | `top-[10px]`    | `top-(10px)`  | PurgeTSS uses parentheses, not square brackets, for arbitrary values |
+| Empty parentheses             | `wh-()`         | (flagged, no auto-fix) | Add a value such as `wh-(10)`                           |
+| Whitespace inside parentheses | `wh-( 200 )`    | `wh-(200)`    | No spaces allowed between `(`, the value, and `)`                |
+| Redundant `px` unit           | `top-(10px)`    | `top-(10)`    | PurgeTSS treats unit-less arbitrary values as pixels             |
+
+### Unknown classes are still silently dropped
+
+The pre-validator only fires on the five patterns above. Any other unknown class — typos, custom utilities not yet declared, vendor classes that are not enabled in `config.cjs` — is **not** reported as a `Class Syntax Error`. Those classes continue to flow into the `// Unused or unsupported classes` comment block in `app.tss`, exactly like before. This keeps the validator focused on actionable mistakes and avoids noise while you sketch out class names.
+
+### v7.8.0 parser fix for negatives inside parentheses
+
+Before v7.8.0, an inverted negative such as `top-(-10)` could be silently misparsed by the arbitrary-value pipeline (the `-` inside the parentheses confused the token matcher, producing wrong or missing TSS output without any warning). v7.8.0 hardens that path: the parser now correctly recognizes `top-(-10)` as authored, classifies it as an inverted-negative-sign error, and surfaces the `Class Syntax Error` block with the `-top-(10)` fix instead of producing silent garbage.
+
 ## Color Properties
 
 You can set arbitrary color values for all available color properties using `hex`, `rgb`, or `rgba` values, directly in XML files or in `config.cjs`.

package/skills/purgetss/references/cli-commands.md

@@ -1,6 +1,12 @@
 # PurgeTSS CLI Commands
 
-> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0**
+> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0 / v7.8.0 / v7.9.0**
+> - **Opacity modifiers on semantic colors (v7.9.0)** — writing `bg-surface/65` (or any opacity modifier on a class mapped to a name in `semantic.colors.json`) now produces a working rule with Light/Dark switching preserved. PurgeTSS auto-derives a `<originalKey>_<alphaPercent>` entry in `semantic.colors.json` with the original `light`/`dark` hex values plus the requested alpha for both modes, then emits the rule against the derived key. Re-runs are idempotent; manual edits with conflicting values halt the build with a `Conflict` error. New alpha entries require one full Titanium build to be picked up — Liveview hot-reload alone does not refresh `semantic.colors.json`.
+> - **Gradient + Window/View/ImageView preset fixes (v7.9.0)** — `theme.Window` / `theme.View` / `theme.ImageView` no longer leak the framework presets (white background, `Ti.UI.SIZE`, iOS `hires: true`) when defined at the top level (replace mode), so a Window declared at `theme.Window` with a `backgroundGradient` no longer ghosts on top of a default `backgroundColor: '#FFFFFF'`. `theme.extend.Window` keeps merging with the defaults as before. Also fixed: tonal palette inversion bug, position-dependent `from`/`to` color ordering after `sort()`, and `bg-gradient-to-X` direction silently dropped when combined with `from-X to-Y` colors.
+> - **Glossary path renamed (v7.9.0, breaking)** — the user-facing glossary output path was renamed from `purgetss/experimental/tailwind-classes/` to `purgetss/glossary/tailwind-classes/`. Tooling or CI that reads from the old path needs updating on upgrade — no transition shim. The `--glossary` flag and command surface are unchanged.
+> - **`images --width <n>` flag (v7.8.0)** — pins Android `mdpi` (= iPhone `@1x`) to a specific pixel width, with larger scales deriving as ×1.5, ×2, ×3, ×4 from that base. Use it for SVG sources from vector editors with disproportionate viewBoxes (Affinity, Illustrator). CLI-only; there is no matching `images:` config property because the right width is per-asset. See [`images` Command](#images-command).
+> - **Class syntax pre-validation (v7.8.0)** — `purgetss` now stops with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known class-name mistakes: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind-style brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`). All offenders are reported in one run. Generic unknown classes still flow into the `// Unused or unsupported classes` block in `app.tss`.
+> - **Negative-values-in-parens parser fix (v7.8.0)** — classes like `top-(-10)`, `mt-(-5)`, and `origin-(-10,-20)` no longer crash with `Cannot read properties of null (reading 'pop')`. The parser now extracts the `(...)` portion first, so a `-` inside the value does not break the split.
 > - **`brand:` config grouped (v7.7.0)** — the flat `brand:` block from v7.6.0 was reorganized into purpose-based sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`. Old projects keep working — newly-generated configs use the grouped form.
 > - **Separate Android brand inputs (v7.7.0)** — `brand` can now use one logo for the general brand set, another for Android launcher icons (`logos.androidLauncher` / `--icon-logo`), and another for Android 12+ splash artwork (`logos.androidSplash` / `--splash-logo`). Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/` or set the paths in `config.cjs`.
 > - **Legacy Android splash fallback (v7.7.0)** — `purgetss brand` now regenerates `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`.
@@ -91,15 +97,14 @@ module.exports = {
       splash: false,         // also generate splash_icon.png × 5
       notification: false    // also generate ic_stat_notify.png × 5
     },
+    ios: {
+      dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+      tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+      darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111111' for an opaque dark bg
+    },
     colors: {
       background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,
-    //   tinted: false,
-    //   darkBackground: '#111111'
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -283,15 +288,14 @@ brand: {
     splash: false,         // also generate splash_icon.png × 5
     notification: false    // also generate ic_stat_notify.png × 5
   },
+  ios: {
+    dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+    tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+    darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111' for an opaque dark bg
+  },
   colors: {
     background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
   },
-  // Optional iOS overrides:
-  // ios: {
-  //   dark: false,           // skip DefaultIcon-Dark.png
-  //   tinted: false,         // skip DefaultIcon-Tinted.png
-  //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png
-  // },
   confirmOverwrites: true  // prompt before overwriting files
 }
 ```
@@ -344,6 +348,7 @@ purgetss images background/                           # re-process one subfolder
 | `--ios` | Only emit iPhone scale variants. Mutually exclusive with `--android`. |
 | `--format <ext>` | Convert all outputs to `webp`, `jpeg`, `png`, `avif`, `gif`, or `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0-100` for lossy formats. Default `85`. |
+| `--width <n>` | (v7.8.0) Pin Android `mdpi` (= iPhone `@1x`) to `<n>` pixels wide. Larger scales derive as ×1.5, ×2, ×3, ×4 from that base; height stays proportional to the source's aspect ratio. Integer in `[1, 8192]`. |
 | `--dry-run` | Preview without writing any files. |
 | `--project <path>` | Project root (defaults to cwd). |
 | `-y, --yes` | Skip the overwrite confirmation prompt. |
@@ -353,6 +358,12 @@ purgetss images background/                           # re-process one subfolder
 
 - `[source]` (optional) — path to override auto-discovery. Resolves first against `purgetss/images/` (short paths like `buttons/btn.png`), then against cwd.
 
+### When to use `--width`
+
+Use `--width <n>` for SVG sources from vector editors with disproportionate viewBoxes — common in Affinity, Illustrator, and other design tools where the viewBox does not match the intended display size. Without the flag, every scale derives from the source's natural pixel size as a 4× master, which can produce unexpected output sizes.
+
+When you pass an SVG without `--width`, the command prints a one-time hint and falls back to the legacy 4× behavior. This is CLI-only; there is no matching `images:` config property because the right width is per-asset.
+
 ### Config block
 
 Defaults live under `images:` in `purgetss/config.cjs`:
@@ -375,6 +386,7 @@ purgetss images background/pink-texture.png            # re-process one file (sh
 purgetss images background/                            # re-process one subfolder
 purgetss images --android                              # only Android densities
 purgetss images --format webp --quality 90             # convert all outputs to WebP
+purgetss images logo.svg --width 256                   # pin SVG output to 256 px @1x/mdpi
 purgetss images --dry-run                              # preview
 ```
 
@@ -412,6 +424,29 @@ purgetss semantic --single '#000000' overlayColor     --alpha 50
 
 When `--dark` is omitted, it defaults to the light hex — useful for overlays/glass surfaces where alpha is the only variation.
 
+### Customizing the class name
+
+The auto-mapping uses the most literal Titanium-style transform: strip `Color`, then kebab-case the rest (e.g. `surfaceColor` → `surface`, `textSecondaryColor` → `text-secondary`). If your design system prefers different names — for example `on-surface` instead of `text`, or nesting the surface family under `DEFAULT` / `high` — edit `config.cjs` after running the `--single` batch:
+
+`./purgetss/config.cjs`
+```javascript
+theme: {
+  extend: {
+    colors: {
+      surface: { DEFAULT: 'surfaceColor', high: 'surfaceHighColor' },
+      'on-surface': 'textColor',
+      'on-surface-variant': 'textSecondaryColor',
+      muted: 'textMutedColor',
+      border: 'borderColor',
+      accent: 'accentColor',
+      overlay: 'overlayColor'
+    }
+  }
+}
+```
+
+The next `purgetss build` picks up the renamed classes. Editing one generated mapping is faster than typing the whole structure from scratch. See [semantic-colors.md](./semantic-colors.md) for the full nested-vs-flat discussion (including the `[object Object]` pitfall when nesting without `DEFAULT`).
+
 ### Smart in-place updates
 
 If a `--single` name matches an existing palette shade — e.g. `purgetss semantic --single '#000' amazon500` while palette `amazon` exists — PurgeTSS narrows the operation to an in-place JSON value edit. The entry stays in its original position, and `config.cjs` is left untouched (the palette already maps to that key).
@@ -482,10 +517,10 @@ After copying the fonts, you can use them in Buttons and Labels. For example, fo
 
 ### Available Font Classes
 
-- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/fontawesome.tss)
-- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialicons.tss)
-- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialsymbols.tss)
-- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/framework7icons.tss)
+- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
+- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
+- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
+- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
 
 ### Copying Specific Font Vendors
 

package/skills/purgetss/references/custom-rules.md

@@ -1,35 +1,49 @@
 # Custom Rules
 
-Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes in `config.cjs`. You can also target specific platforms, devices, or conditional blocks using global variables. Handy when a project spans iOS and Android and you want to keep styles in one place.
+Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes from `config.cjs`. They are the bridge between the utility-first classes you write in XML and the platform-, device-, or condition-specific overrides Titanium projects often need. Because everything lives in a single `config.cjs`, projects that span iOS and Android can keep one source of truth for styling instead of fragmenting rules across multiple `.tss` files.
+
+This file mirrors the official rewrite — section names, examples, and ordering match the upstream docs so cross-referencing stays cheap.
 
 ## Classes, IDs, and Ti Elements
 
-Whether you want to style a Ti Element (also known as a markup element), a custom ID prefixed with a hash (`#`), or a custom class prefixed with a period (`.`), the structure is the same.
+Whether you want to style a Ti Element (a markup element such as `Label`), a custom ID prefixed with `#`, or a custom class prefixed with `.`, the structure inside `config.cjs` is the same. You always declare a key (the selector) whose value is an object containing one or more block keys (`DEFAULT`, `ios`, `android`, `tablet`, `handheld`, or `[if=...]`).
 
 ### Modifier Key
 
-- For Titanium elements, use the exact name of the element, such as `Label`, `Button`, or `ScrollView`.
-- For IDs, use `camelCase` to match the JavaScript convention.
-- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. For example, use `.my-custom-class-name` instead of `.myCustomClassName`.
-
-> **CAUTION -- PurgeTSS v5 or Earlier Projects**
-> If your project started on PurgeTSS v5 or earlier and you now use 7.x.x or later, set `purge.options.missing` to `true` in `config.cjs`. It will report missing classes at the end of `app.tss` so you can update them to the new naming convention.
+- For Titanium elements, use the **exact name** of the element, such as `Label`, `Button`, or `ScrollView`. The casing must match Titanium's API (e.g. `TextField`, not `textfield` or `Text Field`).
+- For IDs, use `camelCase` to match Alloy's JavaScript convention (e.g. `mainBanner` referenced in XML as `id="mainBanner"`). The selector key inside `config.cjs` includes the `#` prefix.
+- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. Use `.my-custom-class-name`, not `.myCustomClassName`. The kebab-case requirement is what most legacy projects trip over when they upgrade.
+
+> **CAUTION — Migrating from PurgeTSS v4 or v5 to v7+**
+>
+> If your project started on PurgeTSS v5 or earlier and you are now on 7.x.x or later, the class-naming convention changed (`camelCase` -> `kebab-case`) and the config moved to ESM-style `config.cjs`. The recommended upgrade path is:
+>
+> 1. **Audit current usage.** Set `purge.options.missing` to `true` in `config.cjs`. PurgeTSS will append a list of missing classes at the end of `app.tss` after the next compile — every entry is a class name you still need to migrate.
+> 2. **Rename selectors.** Convert every `.myCustomClassName` to `.my-custom-class-name` in both XML markup and `config.cjs`. The old camelCase names will not match anymore.
+> 3. **Convert config to `.cjs`.** If your project still uses `purgetss.config.js` or a CommonJS-style file with the old layout, rename the file to `config.cjs` and ensure it sits in `./purgetss/`. The single export must be `module.exports = { theme: { ... } }`.
+> 4. **Re-run `purgetss build`.** Verify the missing-classes list at the end of `app.tss` is empty before turning `missing` back off.
+>
+> Skipping any of these steps tends to surface as silently dropped styles at runtime — the app compiles, but selectors no longer match.
 
 ### Default, Platform, Device, or Conditional Blocks
 
-- To generate a global style, use either the lowercase `default` or the uppercase `DEFAULT` keyword.
-- To target a specific platform, use the `ios` or `android` keywords.
-- To target a specific device, use the `tablet` or `handheld` keywords.
-- To target a condition with a global variable, use the `[if=globalVariableName]` keyword.
+Inside any selector you can declare one or more of the following block keys. They translate to TSS query suffixes at compile time:
+
+- **Global style**: use either the lowercase `default` or the uppercase `DEFAULT` keyword. This becomes the bare selector with no platform/device qualifier.
+- **Specific platform**: use `ios` or `android`. These compile to `[platform=ios]` and `[platform=android]` query suffixes.
+- **Specific device**: use `tablet` or `handheld`. These compile to `[formFactor=tablet]` and `[formFactor=handheld]`.
+- **Conditional via global variable**: use `[if=globalVariableName]`. The exact key is preserved in the generated TSS, so you can reference any `Alloy.Globals.*` boolean.
 
 ### Property Values
 
-- For `Titanium` constants, `Alloy Configuration Values`, or `Global Variables`, always enclose them in quotes.
-- For `color` values, you can use `hex`, `8-digit hex`, `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any of the standard color names. Use hex values if you want to avoid issues with the opacity modifier.
-- For `spacing` values, you can use different types of units: `em`, `rem`, `%`, `px`, `dp`, `cm`, or `in`.
-  - `%`, `px`, `cm`, or `in` are passed through without conversion.
-  - `em` or `rem` values are converted with this formula: `value * 16`.
-  - `dp` removes the unit and keeps the value as-is.
+The way you write property values determines how PurgeTSS emits them in the generated TSS. Pay particular attention to quoting — it is the single most common source of confusion.
+
+- For `Titanium` constants, `Alloy` configuration values, or global variables, **always enclose them in quotes** in `config.cjs` (e.g. `'Ti.UI.SIZE'`, `'Alloy.CFG.iPhoneXNotchSize'`). The quotes are stripped in the generated TSS so the constant resolves at runtime — without them, JavaScript would try to evaluate the constant inside `config.cjs`, which fails because Titanium's globals are not available there.
+- For `color` values, you can use `hex`, `8-digit hex` (with alpha), `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any standard color name. Prefer hex values when you plan to use opacity modifiers — `rgba()` and named colors interact awkwardly with opacity utilities.
+- For `spacing` values you can mix unit types. Each unit follows a specific conversion rule:
+  - `%`, `px`, `cm`, and `in` are passed through to TSS without conversion.
+  - `em` and `rem` values are converted with the formula `value * 16` (so `1rem` becomes `16`).
+  - `dp` removes the unit and keeps the numeric value as-is, since Titanium treats unit-less numeric values as density-independent pixels by default.
 
 ## `config.cjs` File Example
 
@@ -81,7 +95,10 @@ module.exports = {
 };
 ```
 
-`./purgetss/styles/utilities.tss`
+## Custom `./purgetss/styles/utilities.tss` File
+
+PurgeTSS reads `config.cjs` and emits a single `utilities.tss` file that Alloy then merges with the rest of the project's styling. The file below shows what the example above generates — note how block keys translate into TSS query suffixes (`[platform=android]`, `[formFactor=tablet]`, `[if=...]`).
+
 ```tss
 /* Property: TextField */
 /* Description: A single line text field. */

package/skills/purgetss/references/customization-deep-dive.md

@@ -35,15 +35,7 @@ module.exports = {
     }
   },
   brand: {
-    logos: {
-      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
-      // primary: './docs/logo.svg',
-      // androidLauncher: './docs/app-icon.svg',
-      // androidSplash: './docs/splash.svg',
-      // monochrome: './docs/logo-mono.svg',
-      // iosDark: './docs/logo-dark.svg',
-      // iosTinted: './docs/logo-tinted.svg'
-    },
+    logos: {},  // empty = auto-discovers from purgetss/brand/
     padding: {
       ios: '4%',             // iOS aesthetic padding. Range 2-8%.
       androidLegacy: '10%',  // legacy ic_launcher.png padding %
@@ -53,15 +45,14 @@ module.exports = {
       splash: false,         // also generate splash_icon.png × 5
       notification: false    // also generate ic_stat_notify.png × 5
     },
+    ios: {
+      dark: true,            // generate DefaultIcon-Dark.png
+      tinted: true,          // generate DefaultIcon-Tinted.png
+      darkBackground: null   // null = transparent per Apple HIG
+    },
     colors: {
       background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,           // skip DefaultIcon-Dark.png
-    //   tinted: false,         // skip DefaultIcon-Tinted.png
-    //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -85,6 +76,37 @@ The config file has four main sections: `purge`, `brand`, `images`, and `theme`.
 
 `brand:` and `images:` configure the matching CLI commands — see [CLI Commands: `brand`](./cli-commands.md#brand-command) and [CLI Commands: `images`](./cli-commands.md#images-command) for the full option lists. The rest of this page covers `purge` and `theme`.
 
+For `brand`, the structure is grouped by purpose (introduced in v7.7.0, refined since):
+
+- `logos`: optional path overrides when you do not want to rely on `purgetss/brand/` auto-discovery
+- `padding`: visual sizing for iOS, Android legacy, and Android adaptive icons
+- `android`: Android-only optional outputs such as `splash_icon.png` and notification icons
+- `ios`: iOS-only variant toggles (`dark`, `tinted`) and the optional `darkBackground` color
+- `colors`: shared color settings such as the adaptive background and iOS flatten color
+
+For the property-by-property reference, see [Configurable Properties](./configurable-properties.md).
+
+### Overriding logo paths
+
+By default, PurgeTSS auto-discovers logo files from `purgetss/brand/`. If you want to use custom paths, add them to `brand.logos`:
+
+```javascript
+module.exports = {
+  brand: {
+    logos: {
+      primary: './my-logos/main.svg',         // overrides auto-discovered logo.svg
+      androidLauncher: './my-logos/icon.svg', // overrides auto-discovered logo-icon.svg
+      androidSplash: './my-logos/splash.svg', // overrides auto-discovered logo-splash.svg
+      monochrome: './my-logos/mono.svg',      // overrides auto-discovered logo-mono.svg
+      iosDark: './my-logos/dark.svg',         // overrides auto-discovered logo-dark.svg
+      iosTinted: './my-logos/tinted.svg'      // overrides auto-discovered logo-tinted.svg
+    }
+  }
+};
+```
+
+You only need to override the ones you're using. Missing overrides still auto-discover from `purgetss/brand/`.
+
 ### `purge` Section
 
 The `purge` section controls how PurgeTSS removes unused classes or keeps the ones you want.

package/skills/purgetss/references/grid-layout.md

@@ -23,6 +23,9 @@ The snippet below shows the simplest layout. From there, you can mix columns and
 </Alloy>
 ```
 
+> **Visual Reference**
+> The official PurgeTSS docs ship a screenshot at `images/grid-system-example.png` (in the docs source repo) that visualizes how columns, rows, and spans render in a real Alloy view. Consult it when you need a quick mental model of the layout primitives — it is not embedded here, only referenced.
+
 ## Column Grid
 
 ### `grid-cols-{n}`
@@ -49,21 +52,7 @@ If a view uses `.row-span-3`, you can add three more views of the same height to
 
 ## Available Utilities
 
-These are the available utilities to control the grid.
-
-### Gutter Utilities
-
-- `gap-{size}`: Change the gap between rows and columns.
-- `gap-x-{size}` and `gap-y-{size}`: Change the gap between rows and columns independently.
-- `gap-{side}-{size}`: Change the gap on a specific side (t=top, r=right, b=bottom, l=left).
-
-### Column Span Utilities
-
-- `col-span-{n}`: Make an element span `n` columns.
-
-### Row Span Utilities
-
-- `row-span-{n}`: Make an element span `n` rows.
+The official source organizes the grid utilities into these categories. The structure below mirrors the official rewrite so you can map directly between this reference and the upstream docs.
 
 ### Direction Utilities
 
@@ -78,18 +67,48 @@ These are the available utilities to control the grid.
 
 - `grid-rows-{n}`: Create grids with `n` equally sized rows.
 
+### Column Span Utilities
+
+- `col-span-{n}`: Make an element span `n` columns inside a 12-column grid.
+
+### Row Span Utilities
+
+- `row-span-{n}`: Make an element span `n` rows inside a 12-row grid.
+
+### Gutter Utilities
+
+- `gap-{size}`: Change the gap between rows and columns.
+- `gap-x-{size}` and `gap-y-{size}`: Change the gap between rows and columns independently.
+- `gap-{side}-{size}`: Change the gap on a specific side (`t`=top, `r`=right, `b`=bottom, `l`=left).
+
 ### Row Placement Utilities
 
-Control horizontal alignment of elements within a row:
+Control horizontal placement of children inside a row:
 
-| Class | Effect |
-| --- | --- |
-| `start` | Align to the start of the row |
-| `end` | Align to the end of the row |
-| `center` | Align to the center of the row |
+| Class    | Effect                            |
+| -------- | --------------------------------- |
+| `start`  | Align to the start of the row     |
+| `end`    | Align to the end of the row       |
+| `center` | Align to the center of the row    |
 
 These apply to child views inside a `grid-cols-*` container and control horizontal placement within the grid cell.
 
+## Row Placement Use Cases
+
+Combining `row-span-{n}` with `grid-rows-{n}` lets you describe how an element occupies vertical space inside a grid column. The table below covers the most common combinations a Titanium UI tends to need. Every entry is verified against the `grid-rows-{n}` and `row-span-{n}` utilities described in the official source.
+
+| Pattern                                  | Example classes                          | Result                                                                                                  |
+| ---------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Full-height column item                  | `grid-rows-1` + `row-span-1`             | One element fills the entire vertical space of the column.                                              |
+| Two equal stacked items                  | `grid-rows-2` + two children no span     | Two views stack vertically, each taking 50% of the column height.                                       |
+| Tall hero on top, short footer at bottom | `grid-rows-12` + `row-span-9`, `row-span-3` | Hero takes 75% of the column height, footer takes 25%.                                                  |
+| 3-6-3 vertical split                     | `grid-rows-12` + `row-span-3`, `row-span-6`, `row-span-3` | Header / body / footer split. Mirrors the 3-6-3 horizontal split shown for `col-span-{n}`.              |
+| Sidebar that spans every row             | `grid-rows-4` + child with `row-span-4`  | Element occupies the full height of a 4-row column. Useful for vertical separators or full-height nav.  |
+| Two short rows above a tall row          | `grid-rows-12` + `row-span-3`, `row-span-3`, `row-span-6` | Two preview cards above a larger detail panel.                                                          |
+
+> **Note**
+> Just like `col-span-{n}`, the spans you write must add up to the value declared in `grid-rows-{n}` for the layout to fill the column without leftover space.
+
 ## Community-Discovered Patterns
 
 The following notes come from community experience using the PurgeTSS grid system in Titanium projects. They clarify how the grid relates to Titanium's layout engine (not CSS Grid) and offer common use cases for row placement.
@@ -99,8 +118,8 @@ The following notes come from community experience using the PurgeTSS grid syste
 
 ### Common Use Cases for Row Placement
 
-| Class | Use case |
-| --- | --- |
-| `start` | Left-aligned content |
-| `end` | Right-aligned buttons or labels |
-| `center` | Centered content blocks |
+| Class    | Use case                          |
+| -------- | --------------------------------- |
+| `start`  | Left-aligned content              |
+| `end`    | Right-aligned buttons or labels   |
+| `center` | Centered content blocks           |

package/skills/purgetss/references/icon-fonts.md

@@ -1,20 +1,21 @@
 # Icon Font Libraries
 
-> **Official Icon Fonts for PurgeTSS**
-> Previous versions of PurgeTSS included several icon font libraries such as Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons. The list was reduced to keep maintenance manageable.
+> ℹ️ **INFO — Official Icon Fonts for PurgeTSS**
 >
-> These are the official icon fonts supported by PurgeTSS:
+> Older versions of PurgeTSS bundled additional icon font libraries — Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons among them. **Those libraries have been deprecated and removed from the official distribution** to keep maintenance under control. They are still usable, but you must rebuild them yourself with `build-fonts` (see below).
+>
+> The icon fonts officially supported and shipped by PurgeTSS today are:
 >
 > - [Font Awesome 7 Free](https://fontawesome.com) (upgrade with `purgetss il -v=fa`)
-> - [Framework7](https://framework7.io/icons/)
+> - [Framework 7](https://framework7.io/icons/)
 > - [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons)
 > - [Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols)
 
-For the official install flow for those vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
+For the official install flow for the supported vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
 
 ## Recreate Removed Libraries
 
-You can recreate removed libraries using the `build-fonts` command.
+You can recreate any deprecated library using the `build-fonts` command.
 
 ### 1. Download the Libraries
 
@@ -29,7 +30,7 @@ Start by downloading the libraries from their official websites:
 
 Put the desired libraries in the `./purgetss/fonts` folder.
 
-> **INFO**
+> ℹ️ **INFO**
 > Copy the TrueType or OpenType font files and the `.css` file.
 
 ```bash
@@ -67,14 +68,14 @@ The `build-fonts` command generates `./purgetss/styles/fonts.tss` with Unicode c
 /* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
 
 /* boxicons.css */
-'.bxl-meta': { text: '\uef27', title: '\uef27' }
-'.bx-lemon': { text: '\uef28', title: '\uef28' }
-'.bxs-lemon': { text: '\uef29', title: '\uef29' }
+'.bxl-meta': { text: '', title: '' }
+'.bx-lemon': { text: '', title: '' }
+/* ... */
 
 /* lineicons.css */
-'.lni-500px': { text: '\uea03', title: '\uea03' }
-'.lni-add-files': { text: '\uea01', title: '\uea01' }
-'.lni-adobe': { text: '\uea06', title: '\uea06' }
+'.lni-500px': { text: '', title: '' }
+'.lni-add-files': { text: '', title: '' }
+/* ... */
 ```
 
 ### Rename the Style Rule Name
@@ -116,15 +117,15 @@ When you use the `--modules` option, it generates a `./app/lib/purgetss.fonts.js
 const icons = {
   /* boxicons */
   boxicons: {
-    bxlMeta: '\uef27',
-    bxLemon: '\uef28',
-    bxsLemon: '\uef29'
+    bxlMeta: '',
+    bxLemon: ''
+    /* ... */
   },
   /* lineicons */
   lni: {
-    '500px': '\uea03',
-    addFiles: '\uea01',
-    adobe: '\uea06'
+    '500px': '',
+    addFiles: ''
+    /* ... */
   }
 };
 exports.icons = icons;
@@ -147,9 +148,9 @@ New group prefix: `li`
 `./purgetss/styles/fonts.tss`
 ```tss
 /* lineicons/li.css */
-'.li-zoom-out': { text: '\uea02', title: '\uea02' }
-'.li-zoom-in': { text: '\uea03', title: '\uea03' }
-'.li-zip': { text: '\uea04', title: '\uea04' }
+'.li-zoom-out': { text: '', title: '' }
+'.li-zoom-in': { text: '', title: '' }
+/* ... */
 ```
 
 `./app/lib/purgetss.fonts.js`
@@ -163,12 +164,13 @@ const icons = {
 exports.icons = icons;
 ```
 
-> **DANGER**
-> Make sure the new prefix remains unique to avoid conflicts with other class prefixes.
+> 🛑 **DANGER**
+>
+> Make sure the new prefix stays unique so it does not collide with other class prefixes. A duplicate prefix will silently overwrite earlier rules in the generated `fonts.tss`, leaving you with icons that render the wrong glyph at runtime.
 
 ## Community-Discovered Patterns
 
 The following note reflects community experience working with icon fonts that depend on multiple glyphs per icon.
 
-> **Font Awesome Duotone**
+> 🛑 **DANGER — Font Awesome Duotone**
 > Titanium cannot render Font Awesome duotone icons correctly because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.

package/skills/purgetss/references/installation-setup.md

@@ -14,9 +14,35 @@ Install PurgeTSS globally on your machine using [NPM](https://www.npmjs.com/).
 
 ## XML Validation
 
-PurgeTSS v7.5.3 added XML validation that flags any `--` (double-dash) sequence inside XML comments. Titanium's XML parser treats `--` in comments as invalid, and PurgeTSS now detects those sequences before they break the compile step.
+Before purging, PurgeTSS pre-checks every XML file in your project. One case worth calling out: double dashes (`--`) are not allowed inside XML comments. That restriction comes from the XML spec itself, not from PurgeTSS, but many people only run into it once a tool actually parses the file.
 
-If you see a validation warning from PurgeTSS pointing at a view file, replace the offending comment with an alternative marker (for example, `//` or `==`) and re-run the build.
+### Bad comment example
+
+```xml
+<!-- Options: --flag or --value -->
+```
+
+The `--flag` inside that comment is illegal. PurgeTSS stops with a pointer to the offending line:
+
+```text
+XML comment contains illegal "--" sequence ("--flag")
+Fix: Replace "--" with an em dash or reword the comment to avoid double dashes
+```
+
+### Why it fails
+
+Per the XML 1.0 specification, the two-character sequence `--` is reserved as the close-comment indicator (`-->`). It cannot appear anywhere inside a comment body, even mid-string. Any conforming XML parser will reject the document, so catching it up front is more helpful than a confusing TSS output later.
+
+### How to fix
+
+Pick whichever of these reads best:
+
+- Replace `--` with a single Unicode em dash (`—`) so the sequence is no longer two ASCII hyphens.
+- Spell out the dashes (for example, write `dash-dash flag` instead of `--flag`).
+- Move the option list outside the comment — for instance, into a sibling `<!-- Options -->` header followed by documentation in your README or `config.cjs` notes.
+- Rephrase so the two dashes simply do not sit next to each other.
+
+Any of those approaches keeps the comment readable and produces a document that every XML parser will accept.
 
 ## Run PurgeTSS the First Time
 

package/skills/purgetss/references/ios-large-titles.md

@@ -2,13 +2,25 @@
 
 Enabling Large Titles on a Window is not a single-property change. When you pair `largeTitleEnabled` with a `ScrollView` inside a `NavigationWindow` or `TabGroup`, **three interdependent iOS Window properties** must work together — otherwise you get either content hidden behind the nav bar or a visible rendering delay when the window opens.
 
-| Property | Value | Why it matters |
-| --- | --- | --- |
-| `autoAdjustScrollViewInsets` | `true` | iOS automatically adjusts the ScrollView content insets so content starts below the nav bar instead of behind it. |
-| `extendEdges` | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends under the nav/tab bars, producing the translucent blur effect Large Titles depend on. |
-| `largeTitleEnabled` | `true` | Shows the large title that collapses to the standard nav bar title as the user scrolls. |
+## The problem
+
+Setting `largeTitleEnabled: true` in isolation looks like it should be enough — Apple's docs suggest a single switch. In practice, omitting the two companion properties produces three distinct visual bugs that are easy to attribute to "iOS being weird" but really come from the layout engine not having enough information:
+
+1. **Content overlaps behind the nav bar.** The ScrollView starts at `y=0`, hidden under the translucent navigation bar. Users see the top of the list cut off and assume content is missing. This happens when `largeTitleEnabled` is set but `autoAdjustScrollViewInsets` is not.
+2. **The large title flashes / renders with a delay.** On window open, the nav bar region paints empty for a frame or two, then the title pops in. With all three properties present, iOS has the layout it needs *before* the first paint, so the title is there from frame zero. Without `extendEdges`, there is a measurable shadow flash as the system recomputes the layout.
+3. **Collapse glitches on scroll.** The large title shrinks to standard size as the user scrolls down — that is the whole point. But if `extendEdges` is missing, the collapse animation can stutter or skip frames because iOS has to recompute the safe-area inset for every scroll event instead of treating the nav bar as part of the content area.
+
+The fix is not to pick the "right" property. It is to set all three together.
 
-Using only `largeTitleEnabled` causes the nav bar region to render empty for a moment before the title draws. Using `extendEdges` without `autoAdjustScrollViewInsets` pushes content behind the nav bar without compensating the ScrollView insets. All three must be present.
+## The solution: 3 interdependent properties
+
+| Property                     | Value                     | What it does                                                                                                                                |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `autoAdjustScrollViewInsets` | `true`                    | iOS automatically adjusts the ScrollView content insets so content starts below the nav bar instead of behind it. Without this, the ScrollView's first item sits hidden behind the translucent nav bar. |
+| `extendEdges`                | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends under the nav and tab bars, producing the translucent blur/refraction effect Large Titles depend on. Skipping this causes the shadow flash on open and stutters the collapse animation. |
+| `largeTitleEnabled`          | `true`                    | Shows the oversized title in the navigation bar that collapses to standard size as the user scrolls. This is the master switch — the other two are required for it to render correctly. |
+
+Without `autoAdjustScrollViewInsets`, `extendEdges` pushes the content behind the nav bar without compensating the ScrollView insets. Without `extendEdges` + `autoAdjustScrollViewInsets`, using only `largeTitleEnabled` causes the large title to render with a visible delay: the empty nav bar area appears first, then the title draws. With all three properties, iOS calculates the layout before displaying the window.
 
 ## iOS-only — use the `ios:` modifier
 
@@ -39,7 +51,7 @@ Generated style in `./purgetss/styles/utilities.tss`:
 
 Individual windows now only need to override `largeTitleDisplayMode` when they want different collapse behavior (e.g. detail windows).
 
-> **Why an `ios:` block and not an inline `ios:` prefix?** `auto-adjust-scroll-view-insets` and `extend-edges-all` are platform-specific classes — they only exist with `[platform=ios]` suffix in `utilities.tss`. The `ios:` block ensures PurgeTSS resolves the platform-suffixed version. See [apply-directive.md](apply-directive.md) → "Platform-Specific Classes".
+> **Why an `ios:` block and not an inline `ios:` prefix?** `auto-adjust-scroll-view-insets` and `extend-edges-all` are platform-specific classes — they only exist with `[platform=ios]` suffix in `utilities.tss`. The `ios:` block ensures PurgeTSS resolves the platform-suffixed version. See [apply-directive.md](./apply-directive.md) → "Platform-Specific Classes".
 
 ## NavigationWindow example
 
@@ -77,15 +89,15 @@ On iOS, `TabGroup` wraps each `Tab`'s Window in an **implicit NavigationWindow**
 </Alloy>
 ```
 
-## Controlling the collapse behavior: `largeTitleDisplayMode`
+## Controlling large title display
 
-`largeTitleDisplayMode` controls how the title behaves in the navigation stack:
+`largeTitleDisplayMode` controls how the title behaves in the navigation stack — whether it stays large, always shrinks to standard size, or follows the previous window. Combine the three base properties (which make Large Titles render correctly at all) with `largeTitleDisplayMode` per window to get the per-screen behavior you want.
 
-| Mode | Constant | Behavior |
-| --- | --- | --- |
-| Automatic | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` | Inherits from previous window; collapses on scroll. |
-| Always | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS` | Title stays large regardless of scroll position. |
-| Never | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER` | Always uses the standard (small) title size. |
+| Mode      | Constant                                       | Behavior                                                                                                       |
+| --------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Automatic | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` | Inherits the display mode from the previous window in the navigation stack and collapses on scroll. The default. |
+| Always    | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS`    | Title stays large regardless of scroll position. Useful for top-level screens that should never collapse.       |
+| Never     | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER`     | Always uses the standard (small) title size. The right choice for detail windows pushed via `openWindow()`.     |
 
 ### Detail windows: use `large-title-display-mode-never`
 
@@ -126,6 +138,10 @@ Sizing the content height to `Ti.UI.SIZE` is what lets iOS determine whether the
 | `content-w-screen` | `contentWidth` | `Ti.UI.FILL` |
 | `content-h-auto` | `contentHeight` | `Ti.UI.SIZE` |
 
+> 💡 **TIP**
+>
+> Set the three base properties (`autoAdjustScrollViewInsets`, `extendEdges`, `largeTitleEnabled`) as global defaults in `config.cjs`, then override `largeTitleDisplayMode` per window only when needed.
+
 ## Community-Discovered Patterns
 
 ### TabGroup implicit-NavigationWindow wrapping
@@ -138,4 +154,4 @@ When `theme.Window.ios.apply` sets `large-title-enabled` as a default, every pus
 
 ### Cross-reference
 
-The three-property pairing (`autoAdjustScrollViewInsets` + `extendEdges` + `largeTitleEnabled`) is also documented as a reusable global-defaults recipe in [apply-directive.md](apply-directive.md) under *Community-Discovered Patterns → Global Window defaults for Large Titles + ScrollView (iOS)*. Prefer that recipe over per-window repetition whenever the whole app uses Large Titles.
+The three-property pairing (`autoAdjustScrollViewInsets` + `extendEdges` + `largeTitleEnabled`) is also documented as a reusable global-defaults recipe in [apply-directive.md](./apply-directive.md) under *Community-Discovered Patterns → Global Window defaults for Large Titles + ScrollView (iOS)*. Prefer that recipe over per-window repetition whenever the whole app uses Large Titles.

package/skills/purgetss/references/multi-density-images.md

@@ -101,6 +101,62 @@ Recommended sizes for common UI elements (in source pixels, assumed 4×):
 - **List-row thumbnail**: at least `320×320`
 - **Button background**: match the intended display size × 4
 
+## Pinning the output width with `--width`
+
+The 4× master convention works well for raster sources (`.png`, `.jpg`, `.webp`) because the file's pixel dimensions usually reflect the intended 4× size. **SVGs are different.** Their logical size comes from the `viewBox`, and vector editors (Affinity Designer, Illustrator, Figma exports) frequently emit viewBoxes in points or with disproportionate values — a logo can ship with `viewBox="0 0 29559 13542"` and `purgetss images` would happily scale every density from that base, producing files far too large for any UI surface.
+
+`--width <n>` (added in PurgeTSS v7.8.0) is the escape hatch: it pins the **`mdpi` / `@1x`** output width to exactly `n` pixels, then derives every other density from that base. Height stays proportional to the source aspect ratio — you only specify width.
+
+```bash
+purgetss images logo.svg --width 256
+```
+
+### Multiplier table
+
+The pinned width drives the scale for every density:
+
+| Scale | Multiplier | Width if `--width 256` |
+| --- | --- | --- |
+| `mdpi` / `@1x` | ×1 | 256 |
+| `hdpi` | ×1.5 | 384 |
+| `xhdpi` / `@2x` | ×2 | 512 |
+| `xxhdpi` / `@3x` | ×3 | 768 |
+| `xxxhdpi` | ×4 | 1024 |
+
+### Validation
+
+`--width` accepts integers in `[1, 8192]`. Out-of-range values are rejected immediately and the command exits without writing anything:
+
+```bash
+purgetss images logo.svg --width 0
+# Invalid --width '0'. Must be an integer between 1 and 8192.
+
+purgetss images logo.svg --width 9000
+# Invalid --width '9000'. Must be an integer between 1 and 8192.
+
+purgetss images logo.svg --width abc
+# Invalid --width 'NaN'. Must be an integer between 1 and 8192.
+```
+
+The upper bound of `8192` exists because `--width 8192` already produces a `xxxhdpi` output of 32 768 px — that's Sharp's render ceiling and well beyond anything a Titanium UI needs.
+
+### The hint message for unflagged SVGs
+
+Whenever you run `purgetss images` against an SVG **without** `--width`, PurgeTSS prints a one-time hint:
+
+```text
+⚠  SVG source detected without --width. Output sizes will be derived from
+   each SVG's viewBox (treated as a 4× master).
+   For SVGs from vector editors with disproportionate viewBoxes, pass
+   --width <n> (e.g. --width 256) to pin the @1x/mdpi width.
+```
+
+This is a hint, **not an error**. The legacy 4×-from-viewBox behavior still runs in the same invocation. If your SVG has a sensible viewBox (`300×150` for a 300px-wide logo at 1×, etc.), the default is fine. If the viewBox is in points or noticeably larger than expected, re-run with `--width <n>` for predictable scaling.
+
+### Why CLI-only (no `images:` config equivalent)
+
+`--width` deliberately has **no matching property** in the `images:` block of `purgetss/config.cjs`. The reason: width is a **per-asset** decision, not a project-wide setting. A hero illustration, an inline icon, and a logo each need different widths — pinning a single value globally would make most outputs wrong. Project-wide settings like `quality` or `format` belong in `config.cjs`; per-invocation values like `--width` only make sense as CLI flags passed against the specific source you're regenerating.
+
 ## The `images:` config section
 
 On the first run, `purgetss images` injects an `images:` block into your existing `purgetss/config.cjs` (between `brand:` and `theme:`) with these defaults:
@@ -291,6 +347,7 @@ If you only tweaked CSS classes (no image changes), you don't need to re-run `pu
 | --- | --- |
 | `--format <ext>` | Convert all outputs to: `webp`, `jpeg`, `png`, `avif`, `gif`, `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0–100` for lossy formats. Default `85`. |
+| `--width <n>` | (v7.8.0) Pin `mdpi` / `@1x` output width to `n` pixels; `[1, 8192]`. Other densities derive from this base (×1.5 / ×2 / ×3 / ×4). Most useful for SVG sources with non-standard viewBoxes. CLI-only — no `config.cjs` equivalent because width is per-asset. |
 
 **Project & output**
 

package/skills/purgetss/references/opacity-modifier.md

@@ -53,8 +53,17 @@ module.exports = {
 '.bg-primary': { backgroundColor: '#ce10cc' }
 ```
 
-> **CAUTION -- Semantic Colors**
-> Semantic colors cannot be modified with the opacity modifier because they are defined as an object with light and dark values.
+## Semantic colors
+
+Since v7.9.0, opacity modifiers also work on classes that resolve to a semantic color. Any class mapped to a semantic color entry can use `/<percent>` syntax.
+
+```xml
+<View class="bg-surface/65" />
+```
+
+PurgeTSS detects that `bg-surface` maps to the semantic name `surfaceColor`, then derives a new semantic key (`surfaceColor_65`) with the original `light` and `dark` hex values plus the requested alpha for both modes. It writes that key back to `semantic.colors.json` and emits the rule against the derived key. Light/Dark switching still works.
+
+See [Semantic colors — Opacity modifier auto-derivation](./semantic-colors.md#opacity-modifier-auto-derivation) for the full mechanics.
 
 ## Community-Discovered Patterns
 

package/skills/purgetss/references/semantic-colors.md

@@ -302,6 +302,48 @@ Once the JSON and the `config.cjs` mapping are in place, you use the semantic cl
 
 When the appearance changes — whether from `Appearance.set(...)` or a system-level toggle — Titanium resolves each semantic color name to its `light` or `dark` value automatically. No event listeners, no manual repaint.
 
+### Opacity modifier auto-derivation
+
+As of PurgeTSS v7.9.0, you can apply the `/N` opacity modifier to **any class that resolves to a semantic name** in `semantic.colors.json`, and PurgeTSS will derive a new semantic key with that alpha pre-applied for both `light` and `dark` modes. This works for `bg-*`, `text-*`, `border-*`, and any other color-accepting utility whose class is mapped through `theme.extend.colors` in `config.cjs`.
+
+```xml
+<View class="bg-surface/65" />
+<Label class="text-on-surface/80" text="Subtle" />
+<View class="border border-accent/40" />
+```
+
+On the next `purgetss build` (or plain `purgetss`) run, the toolchain executes a three-step flow:
+
+1. **Detects the mapping** — PurgeTSS sees that, for example, `bg-surface` is mapped to the semantic name `surfaceColor` via `config.cjs`.
+2. **Derives a new key** — it adds `surfaceColor_65` (naming convention: `<originalKey>_<alphaPercent>`, underscore + integer percent) to `semantic.colors.json`, copying the original hex values for both modes and tagging each with `alpha: "65"`:
+
+   ```json
+   "surfaceColor_65": {
+     "light": { "color": "#F9FAFB", "alpha": "65" },
+     "dark":  { "color": "#0f172a", "alpha": "65" }
+   }
+   ```
+
+3. **Emits the rule against the derived key** — for example, `'.bg-surface/65': { backgroundColor: 'surfaceColor_65' }`. Light/Dark switching keeps working because Titanium handles the lookup like any other semantic color. The same flow runs for opacity inside an `apply:` string in `config.cjs`.
+
+#### Idempotency and the `Conflict` error
+
+Re-runs are idempotent: existing derived keys are reused, never duplicated. If you manually edit a derived key with values that disagree with what PurgeTSS would generate (different base color, different alpha, different shape), the next build halts with a `Conflict` error instead of silently overwriting your edits — you have to either revert the manual change or remove the derived key so it can be regenerated cleanly.
+
+> **DANGER**
+>
+> **Native rebuild required for new alpha entries**
+>
+> `semantic.colors.json` is read at **native build time**, not at runtime. The first time a brand-new opacity variant is auto-derived (a class like `bg-surface/65` you've never used before), the running app **will not see it** until the next full Titanium build. Liveview hot-reload alone does **not** refresh `semantic.colors.json` for the running app — only the native binary does.
+>
+> In practice: after introducing a new opacity class, run `purgetss build` once, then start a fresh native build (`appc run` / `ti build`) before resuming your usual Liveview cycle. Subsequent runs of the *same* `/N` value reuse the existing derived key and need no extra rebuild.
+
+#### Constraints
+
+- **Alpha range**: integer `0–100`, matching the standard opacity modifier syntax. Values outside this range are rejected.
+- **Base key must exist**: the semantic name behind the class (`surfaceColor` in the example) must already exist in `semantic.colors.json`. If it doesn't, PurgeTSS emits a warning for direct XML usage or throws an Error for `apply:` directives, with three concrete suggestions in the message.
+- **Naming is fixed**: the derived key is always `<originalKey>_<alphaPercent>` — underscore + integer percent. This mirrors the `/65` you typed and stays quote-free in `config.cjs` if you ever need to reference it manually.
+
 ## Using semantic colors in controllers
 
 Semantic colors also work from JavaScript. Three patterns cover the cases you'll hit.
@@ -368,10 +410,11 @@ A minimal semantic palette that covers most app surfaces:
 | Cards / elevated   | `surfaceHighColor`   | `#FFFFFF` | `#1e293b` | `bg-surface-high`          |
 | Primary text       | `textColor`          | `#111827` | `#f1f5f9` | `text-on-surface`          |
 | Secondary text     | `textSecondaryColor` | `#6B7280` | `#94a3b8` | `text-on-surface-variant`  |
+| Muted text         | `textMutedColor`     | `#9CA3AF` | `#64748b` | `text-muted`               |
 | Borders / dividers | `borderColor`        | `#E5E7EB` | `#334155` | `bg-border`                |
 | Accent             | `accentColor`        | `#3B82F6` | `#60a5fa` | `text-accent`, `bg-accent` |
 
-Start with these 5-6 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
+Start with these 6-7 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
 
 ## Related
 

package/skills/purgetss/references/tikit-components.md

@@ -316,9 +316,7 @@ Colors: `black`, `dark`, `light`, and `white` themes that affect background and
 
 Use this for code examples. Set `copy="true"` to add a copy button.
 
-> **Community-Discovered Pattern — Pro tip**
->
-> For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config.
+**Pro tip — recommended monospace fonts:** For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config. (Source: official tikit docs, `tikit.md` line ~390.)
 
 **Localization:** The copy button uses `L('copy', 'Copy')` for its title and `L('code_copied', 'Code copied!')` for the confirmation message. Add these keys to your `strings.xml` files for translation.