@maccesar/titools 4.23.1 → 5.1.0

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

@@ -81,7 +81,7 @@ $.navWin.open()
 
 > **WARNING**
 >
-> 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.
+> Call `Appearance.init()` **before** `$.navWin.open()` (or whichever window you open first). Both official pages place the call before the first window opens.
 
 ### 3. Build an Appearance toggle
 
@@ -158,7 +158,61 @@ function 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.
 
-> **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.
+Semantic colors apply anywhere you use `bg-*`, `text-*`, and `border-*` classes: Windows, Views, Labels, Buttons, TextFields, TextAreas, ListViews, and custom classes that reference a semantic name. One appearance switch updates the UI.
+
+The official setup guide declares the `onClick` handlers (`selectDark`, `selectLight`, `selectSystem`) as named functions at the top level of the controller.
+
+### Minimal Alloy example
+
+The API page uses a flat three-color mapping and a single toggle button:
+
+`app/assets/semantic.colors.json`
+```json
+{
+  "surfaceColor": { "light": "#F8FAFC", "dark": "#0F172A" },
+  "textColor": { "light": "#0F172A", "dark": "#F8FAFC" },
+  "accentColor": { "light": "#2563EB", "dark": "#60A5FA" }
+}
+```
+
+`purgetss/config.cjs`
+```js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        surface: 'surfaceColor',
+        text: 'textColor',
+        accent: 'accentColor'
+      }
+    }
+  }
+}
+```
+
+`app/views/index.xml`
+```xml
+<Alloy>
+  <Window class="bg-surface">
+    <Label class="text-text" text="Appearance" />
+    <Button class="bg-accent text-white" title="Toggle" onClick="toggleAppearance" />
+  </Window>
+</Alloy>
+```
+
+`app/controllers/index.js`
+```js
+const { Appearance } = require('purgetss.ui')
+
+Appearance.init()
+
+function toggleAppearance() {
+  Appearance.toggle()
+  Ti.API.info(`Mode: ${Appearance.get()}`)
+}
+
+$.index.open()
+```
 
 ## Titanium Classic
 
@@ -190,9 +244,18 @@ const toggleButton = Ti.UI.createButton({
   backgroundColor: 'accentColor'
 })
 
+function updateModeLabel() {
+  title.text = `Mode: ${Appearance.get()}`
+}
+
 function toggleAppearance() {
   Appearance.toggle()
-  title.text = `Mode: ${Appearance.get()}`
+  updateModeLabel()
+}
+
+function useSystemAppearance() {
+  Appearance.set('system')
+  updateModeLabel()
 }
 
 function disposeWindow() {
@@ -205,6 +268,8 @@ window.add(title)
 window.add(toggleButton)
 window.addEventListener('close', disposeWindow)
 window.open()
+
+// Call useSystemAppearance() from your own System mode control.
 ```
 
 Run a full native build after adding or changing semantic keys. A LiveView reload alone does not refresh Titanium's native color catalog. The `purgetss semantic` command can create the JSON for a Classic project; it writes only `Resources/semantic.colors.json`, not `config.cjs`, TSS, or utility mappings.
@@ -261,7 +326,7 @@ app startup
 ## Related
 
 - [semantic-colors.md](./semantic-colors.md) — defining `app/assets/semantic.colors.json` and mapping the color names in `config.cjs` so views actually respond to mode changes.
-- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — the `purgetss semantic` command; Alloy also receives `config.cjs` mappings, while Classic receives only the native JSON.
+- [color-commands.md#semantic-command](./color-commands.md#semantic-command) — the `purgetss semantic` command; Alloy also receives `config.cjs` mappings, while Classic receives only the native JSON.
 - [customization-deep-dive.md](./customization-deep-dive.md) — full `config.cjs` structure, including the `theme.extend.colors` section where semantic names are registered.
 - [purgetss-ui-classic.md](./purgetss-ui-classic.md) — generated module path, Classic animation factory, method contracts, and cleanup.
 
@@ -269,5 +334,5 @@ app startup
 
 These field-tested patterns are now also confirmed by the official Appearance documentation:
 
-- **Always call `Appearance.init()` before opening the first window.** Opening the window first causes a visible flicker on cold launch as the UI repaints from the system default to the saved mode. The official best-practices guide puts `Appearance.init()` on line 3 of `app/controllers/index.js`, immediately before `$.navWin.open()`, for exactly this reason.
+- **Always call `Appearance.init()` before opening the first window.** The official best-practices guide calls `Appearance.init()` right after the `require` in `app/controllers/index.js`, before `$.navWin.open()`. The docs give no reason beyond the ordering; the flicker on cold launch when the window opens first is a community observation.
 - **`toggle()` is not a three-state cycle.** It only alternates between `'light'` and `'dark'`. If the saved mode is `'system'`, the first `toggle()` call lands on `'dark'`. Build a cycle yourself with `get()` + `set(...)` when you need one.

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

@@ -273,7 +273,7 @@ module.exports = {
     extend: {
       ImageView: {
         ios: {
-          apply: 'hires-true'
+          apply: 'hires'
         }
       },
       View: {
@@ -467,19 +467,27 @@ Constants like `Ti.UI.iOS.CLIP_MODE_ENABLED` or `Ti.UI.iOS.StatusBar.LIGHT_CONTE
 
 **See the dedicated reference: [`ios-large-titles.md`](./ios-large-titles.md)** — it covers the full pattern (three-property pairing, global-defaults recipe, TabGroup implicit NavigationWindow behavior, detail-window opt-out, and the ScrollView `content-w-screen` / `content-h-auto` pairing).
 
-Minimal recap — when Large Titles are in use, set the base iOS Window defaults once via `apply` in `config.cjs` rather than repeating them in every XML view:
+Minimal recap — when Large Titles are in use, set the base iOS Window defaults once via `apply` in `config.cjs` rather than repeating them in every XML view. Put it under `theme.extend.Window` so the framework's white `backgroundColor` default is kept (a top-level `theme.Window` is replace mode and drops it):
 
 `./purgetss/config.cjs`
 ```javascript
 module.exports = {
   theme: {
-    Window: {
-      ios: {
-        apply: 'auto-adjust-scroll-view-insets extend-edges-all large-title-enabled'
+    extend: {
+      Window: {
+        ios: {
+          apply: 'auto-adjust-scroll-view-insets extend-edges-all large-title-enabled'
+        }
       }
     }
   }
 };
 ```
 
-The `ios:` block (not an inline `ios:` prefix) is required because these classes only exist with a `[platform=ios]` suffix — see "Platform-Specific Classes" above. The *why* (rendering delay vs content-behind-nav-bar), the display-mode constants, and per-window overrides live in [`ios-large-titles.md`](./ios-large-titles.md) and in the official PurgeTSS docs at [Best Practices → Large Titles on iOS](https://purgetss.com/docs/best-practices/3-large-titles-on-ios).
+`./purgetss/styles/utilities.tss`
+```tss
+'Window': { backgroundColor: '#FFFFFF' }
+'Window[platform=ios]': { autoAdjustScrollViewInsets: true, extendEdges: [ Ti.UI.EXTEND_EDGE_ALL ], largeTitleEnabled: true }
+```
+
+These three classes exist without a platform suffix in `utilities.tss`, so they would resolve from a `default` block too; the `ios:` block is what scopes the generated rule to `[platform=ios]` so Android never receives these properties. The *why* (rendering delay vs content-behind-nav-bar), the display-mode constants, and per-window overrides live in [`ios-large-titles.md`](./ios-large-titles.md) and in the official PurgeTSS docs at [Best Practices → Large Titles on iOS](https://purgetss.com/docs/best-practices/large-titles-on-ios).

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

@@ -5,7 +5,7 @@ When you need a one-off value that is not in the defaults, use arbitrary values
 > **INFO**
 > To generate an arbitrary style, use parentheses notation with almost any default utility class.
 >
-> Square bracket notation (`[10px]`) is **not supported** because Titanium handles platform and conditional statements in `.tss` files differently. Use parentheses (`(10px)`) instead.
+> Square bracket notation (`[10]`) is **not supported** because Titanium already uses square brackets for platform and conditional statements in `.tss` files. Use parentheses (`(10)`) instead.
 
 <!-- TOC-START -->
 ## Contents
@@ -26,19 +26,25 @@ Starting with PurgeTSS v7.8.0, the build runs a pre-validation pass over class n
 
 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
+- `Class:` the offending class name (as authored)
+- `File:` the first file where it appears (plus a count of other locations, if any)
+- `Line:` the line number inside that file
+- `Content:` the full content of that line
+- `Issue:` what is wrong
+- `Fix:` a suggestion with the corrected class name
 
-Example shape:
+Example output:
 
 ```
-Class Syntax Error
-  File: app/views/index.xml
-  Line: 12
-  Found: top-(-10)
-  Fix:   -top-(10)
+::PurgeTSS:: Class Syntax Error
+   Class: "top-(-10)"
+   File: "app/views/index.xml"
+   Line: 12
+   Content: <View class="top-(-10)" />
+
+   Issue: Negative sign is inside the parentheses
+   Fix: Use "-top-(10)" — PurgeTSS expects the "-" prefix BEFORE the rule, not inside the value
+::PurgeTSS:: Found 1 class syntax error — fix the class above and re-run purgetss
 ```
 
 ### Detected patterns
@@ -48,7 +54,7 @@ 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        |
-| Square-bracket notation       | `top-[10px]`    | `top-(10px)`  | PurgeTSS uses parentheses, not square brackets, for arbitrary values (v7.10.1 reworded the error from `Tailwind-style brackets "[ ]"` to `Square brackets "[ ]" are not supported`) |
+| Square-bracket notation       | `top-[10]`      | `top-(10)`    | PurgeTSS uses parentheses, not square brackets, for arbitrary values (v7.10.1 reworded the error from `Tailwind-style brackets "[ ]"` to `Square brackets "[ ]" are not supported`) |
 | 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             |
@@ -57,9 +63,11 @@ The validator catches five narrow, actionable mistakes:
 
 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.
 
+> **Units: write arbitrary values unitless.** Because of the redundant-`px` rule, any class like `m-(50px)`, `w-(2300px)` or `text-(48px)` halts the purge. Write `m-(50)`, `w-(2300)`, `text-(48)` instead; other units such as `rem`, `in` or `%` are not flagged.
+
 ### 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.
+Before v7.8.0, a hyphen inside the value (e.g. `top-(-10)`, `mt-(-5)`, `rotate-(-45)`, `origin-(-10,-20)`) crashed the arbitrary-value parser with an unhandled `Cannot read properties of null (reading 'pop')` exception. v7.8.0 rewrote the parser to extract the `(...)` part first, so the value can contain any characters, and classes with empty values (`wh-()`) or unbalanced parentheses (`wh-(`) now produce a "not yet supported" comment instead of invalid TSS. `top-(-10)` itself is now caught by the pre-validator as an inverted negative sign, with the `-top-(10)` fix.
 
 ## Arbitrary nesting depth in `theme` objects (v7.10.0)
 
@@ -168,23 +176,32 @@ You can set an arbitrary value for any of the following color properties:
 - `active-tint-` (*hex-rgb-or-rgba-value*)
 - `active-title-` (*hex-rgb-or-rgba-value*)
 - `badge-` (*hex-rgb-or-rgba-value*)
+- `badge-bg-` (*hex-rgb-or-rgba-value*)
+- `badge-text-` (*hex-rgb-or-rgba-value*)
 - `bar-` (*hex-rgb-or-rgba-value*)
 - `bg-` (*hex-rgb-or-rgba-value*)
+- `bg-disabled-` (*hex-rgb-or-rgba-value*)
 - `bg-focused-` (*hex-rgb-or-rgba-value*)
 - `bg-selected-` (*hex-rgb-or-rgba-value*)
 - `bg-selected-from-` (*hex-rgb-or-rgba-value*)
 - `bg-selected-to-` (*hex-rgb-or-rgba-value*)
 - `border-` (*hex-rgb-or-rgba-value*)
+- `colors-` (*hex-rgb-or-rgba-value*)
+- `content-scrim-` (*hex-rgb-or-rgba-value*)
 - `current-page-indicator-` (*hex-rgb-or-rgba-value*)
 - `date-time-` (*hex-rgb-or-rgba-value*)
 - `disabled-` (*hex-rgb-or-rgba-value*)
 - `drop-shadow-` (*hex-rgb-or-rgba-value*)
 - `from-` (*hex-rgb-or-rgba-value*)
 - `highlighted-` (*hex-rgb-or-rgba-value*)
+- `hint-text-` (*hex-rgb-or-rgba-value*)
+- `icon-` (*hex-rgb-or-rgba-value*)
 - `image-touch-feedback-` (*hex-rgb-or-rgba-value*)
 - `indicator-` (*hex-rgb-or-rgba-value*)
 - `keyboard-toolbar-` (*hex-rgb-or-rgba-value*)
+- `light-` (*hex-rgb-or-rgba-value*)
 - `nav-tint-` (*hex-rgb-or-rgba-value*)
+- `navigation-icon-` (*hex-rgb-or-rgba-value*)
 - `on-tint-` (*hex-rgb-or-rgba-value*)
 - `page-indicator-` (*hex-rgb-or-rgba-value*)
 - `paging-control-` (*hex-rgb-or-rgba-value*)
@@ -193,17 +210,21 @@ You can set an arbitrary value for any of the following color properties:
 - `results-bg-` (*hex-rgb-or-rgba-value*)
 - `results-separator-` (*hex-rgb-or-rgba-value*)
 - `selected-` (*hex-rgb-or-rgba-value*)
+- `selected-bg-` (*hex-rgb-or-rgba-value*)
 - `selected-button-` (*hex-rgb-or-rgba-value*)
 - `selected-subtitle-` (*hex-rgb-or-rgba-value*)
 - `selected-text-` (*hex-rgb-or-rgba-value*)
 - `separator-` (*hex-rgb-or-rgba-value*)
 - `shadow-` (*hex-rgb-or-rgba-value*)
+- `status-bar-bg-` (*hex-rgb-or-rgba-value*)
 - `subtitle-` (*hex-rgb-or-rgba-value*)
+- `subtitle-text-` (*hex-rgb-or-rgba-value*)
 - `tabs-bg-` (*hex-rgb-or-rgba-value*)
 - `tabs-bg-selected-` (*hex-rgb-or-rgba-value*)
 - `text-` (*hex-rgb-or-rgba-value*)
 - `thumb-tint-` (*hex-rgb-or-rgba-value*)
 - `tint-` (*hex-rgb-or-rgba-value*)
+- `tint-color-` (*hex-rgb-or-rgba-value*)
 - `title-` (*hex-rgb-or-rgba-value*)
 - `title-attributes-` (*hex-rgb-or-rgba-value*)
 - `title-attributes-shadow-` (*hex-rgb-or-rgba-value*)
@@ -211,10 +232,11 @@ You can set an arbitrary value for any of the following color properties:
 - `to-` (*hex-rgb-or-rgba-value*)
 - `touch-feedback-` (*hex-rgb-or-rgba-value*)
 - `track-tint-` (*hex-rgb-or-rgba-value*)
+- `view-shadow-` (*hex-rgb-or-rgba-value*)
 
 ## Spacing Properties
 
-You can set arbitrary values for most size and dimension properties using `rem`, `px`, or `pt` values, directly in XML files or in `config.cjs`.
+You can set arbitrary values for most size and dimension properties using unitless numbers or units such as `rem`, `in`, or `%`, directly in XML files or in `config.cjs`. A `px` suffix is rejected by the pre-validator (see above).
 
 ```xml
 <Alloy>
@@ -274,6 +296,7 @@ You can set arbitrary values for most size and dimension properties using `rem`,
 - Width and height
   - `h-` (*any-size-value-and-unit*)
   - `w-` (*any-size-value-and-unit*)
+  - `wh-` (*any-size-value-and-unit*)
 - `indentation-level-` (*any-size-value-and-unit*)
 - `keyboard-toolbar-h-` (*any-size-value-and-unit*)
 - Left and right button padding
@@ -327,10 +350,15 @@ You can set arbitrary values for most size and dimension properties using `rem`,
   - `rounded-t-` (*any-size-value-and-unit*)
   - `rounded-tl-` (*any-size-value-and-unit*)
   - `rounded-tr-` (*any-size-value-and-unit*)
+  - `rounded-corners-` (*four-comma-separated-values*), e.g. `rounded-corners-(1,2,3,4)` → `borderRadius: [1, 2, 3, 4]`
+  - `rounded-full-` (*any-size-value-and-unit*), e.g. `rounded-full-(40)` → `width: 40, height: 40, borderRadius: 20`
 - `row-h-` (*any-size-value-and-unit*)
 - `section-header-top-padding-` (*any-size-value-and-unit*)
 - `separator-h-` (*any-size-value-and-unit*)
 - `shadow-radius-` (*any-size-value-and-unit*)
+- Target image height and width
+  - `target-image-h-` (*any-size-value-and-unit*)
+  - `target-image-w-` (*any-size-value-and-unit*)
 - xOffset and yOffset
   - `x-offset-` (*any-size-value-and-unit*)
   - `y-offset-` (*any-size-value-and-unit*)
@@ -344,36 +372,44 @@ You can set arbitrary values for the following properties, like border radius an
 - `active-tab-` (*number-value*)
 - `border-width-` (*number-value*)
 - `cache-size-` (*number-value*)
+- `cancel-` (*number-value*)
 - `count-down-` (*in-milliseconds*)
 - `delay-` (*in-milliseconds*)
+- `destructive-` (*number-value*)
 - `duration-` (*in-milliseconds*)
 - `elevation-` (*number-value*)
 - `font-` (*valid-font-weight-value*)
 - `horizontal-margin-` (*decimal-value*)
+- `index-` (*number-value*)
 - `lines-` (*number-value*)
+- `max-` (*number-value*)
 - `max-length-` (*number-value*)
 - `max-lines-` (*number-value*)
 - `max-zoom-scale-` (*decimal-value*)
+- `maximum-` (*number-value*)
 - `min-zoom-scale-` (*decimal-value*)
 - `min-` (*number-value*)
+- `minimum-` (*number-value*)
 - `minimum-text-` (*number-value*)
 - `opacity-` (*decimal-value-from-0-to-1*)
 - `origin-` (*x-and-y-coordinates*)
 - `paging-control-alpha-` (*decimal-value-from-0-to-1*)
 - `paging-control-timeout-` (*in-milliseconds*)
+- `preferred-` (*number-value*)
 - `repeat-count-` (*number-value*)
 - `repeat-` (*number-value*)
 - `rotate-` (*number-value*)
 - `scale-` (*decimal-value*)
 - `text-size-` (*number-value*)
 - `timeout-` (*in-milliseconds*)
+- `value-` (*number-value*)
 - `vertical-margin-` (*decimal-value*)
 - `z-` (*number-value*)
 - `zoom-scale-` (*decimal-value*)
 
 ## Examples
 
-You can use any supported units depending on the property you are generating. Use `hex` or `rgba` values for any color property, or `rem` or `px` for position and sizing properties.
+You can use any supported units depending on the property you are generating. Use `hex` or `rgba` values for any color property, or unitless numbers or `rem` for position and sizing properties.
 
 ### Credit Card
 
@@ -381,7 +417,7 @@ You can use any supported units depending on the property you are generating. Us
 <Alloy>
   <Window class="bg-(#53606b)">
     <View class="w-(2in) h-(3.5in) bg-(#4C61E4) rounded-(20)">
-      <View class="m-(50px) h-screen w-screen">
+      <View class="m-(50) h-screen w-screen">
         <View class="horizontal ml-0 mt-0">
           <View class="w-(3rem) h-(3rem) rounded-(1.5rem) opacity-(0.35) bg-white" />
           <View class="-ml-(20) w-(3rem) h-(3rem) rounded-(1.5rem) opacity-(0.25) bg-white" />
@@ -407,10 +443,10 @@ Try this example on an iPad or tablet.
 ```xml
 <Alloy>
   <Window class="bg-white">
-    <View class="bg-(#1B6F3F) w-(2300px) h-(1600px) ml-0 mt-0">
-      <View class="mt-(100px) h-(200px) left-(150px) horizontal">
-        <Label class="fas fa-cloud text-(48px) text-white" />
-        <Label class="ml-(30px) text-(48px) h-(200px) font-bold text-white">ZULTYS</Label>
+    <View class="bg-(#1B6F3F) w-(2300) h-(1600) ml-0 mt-0">
+      <View class="mt-(100) h-(200) left-(150) horizontal">
+        <Label class="fas fa-cloud text-(48) text-white" />
+        <Label class="ml-(30) text-(48) h-(200) font-bold text-white">ZULTYS</Label>
       </View>
     </View>
   </Window>
@@ -422,9 +458,9 @@ Try this example on an iPad or tablet.
 ```xml
 <Alloy>
   <Window class="bg-(#53606b)" backgroundImage="https://i.pinimg.com/originals/ab/70/a1/ab70a19f087cc9ba2b03e3bee71acc3e.jpg">
-    <View class="h-(150px) bg-(#53A500) horizontal mt-0 w-screen">
-      <Label class="w-(4.5rem) text-(16px) h-(150px) text-(#12681E) text-center font-bold" text="Home" />
-      <Label class="w-(4.5rem) text-(16px) h-(150px) text-(#12681E) bg-(#6DB400) text-center font-bold" text="News" />
+    <View class="h-(150) bg-(#53A500) horizontal mt-0 w-screen">
+      <Label class="w-(4.5rem) text-(16) h-(150) text-(#12681E) text-center font-bold" text="Home" />
+      <Label class="w-(4.5rem) text-(16) h-(150) text-(#12681E) bg-(#6DB400) text-center font-bold" text="News" />
     </View>
   </Window>
 </Alloy>

package/skills/purgetss/references/brand-padding-geometry.md

@@ -0,0 +1,105 @@
+# Brand Padding & Geometry
+
+How `purgetss brand` sizes the logo inside each piece: per-piece padding, how the source is read and how sharp the output is, the shared splash rule, rounded non-icon artwork, and the Android adaptive mask math.
+
+For the `brand` command itself, its pieces and config, see [App Icons & Branding](./app-branding.md).
+
+## Padding guidance
+
+Padding belongs to the piece, not to the project. Each piece has its own key and its own flag:
+
+| Piece | Config | Flag | Default |
+| --- | --- | --- | --- |
+| `adaptive` | `brand.adaptive.padding` | `--android-adaptive-padding` | `18%` |
+| `legacy-icon` | `brand.legacyIcon.padding` | `--android-legacy-padding` | `10%` |
+| `appicon` | `brand.appicon.padding` | `--appicon-padding` | `10%` |
+| `icon` | `brand.icon.padding` | `--ios-padding` | `0%` |
+| `feature-graphic` | `brand.featureGraphic.padding` | `--feature-graphic-padding` | `12%` |
+| `launch-logo` | `brand.launchLogo.padding` | `--launch-logo-padding` | `12%` |
+| `android-splash` | `brand.androidSplash.padding` | `--android-splash-padding` | `26%` |
+| `ios-splash` | `brand.iosSplash.padding` | `--ios-splash-padding` | `26%` |
+
+`--padding` is a shortcut for the two Android launcher paddings in a single run, and `--splash-padding` for the two splash paddings. `--ios-padding` moves the four square iOS/marketplace pieces together (`icon`, `dark`, `tinted`, `marketplace`); in config each of them has its own key.
+
+There is deliberately **no global padding value that cascades down**. The defaults answer to different constraints: `18%` answers to the Android launcher mask, while finished square iOS/store artwork stays full-bleed at `0%`. One inherited number could silently break the launcher mask or add an unwanted frame to finished artwork. `background`, which has no such trap, is inherited from `brand.background`.
+
+### How the source is read, and how sharp the output is
+
+Two things are worth knowing about what happens to your `logo.svg` or `logo.png` before any padding is applied.
+
+**The container is what counts, not the artwork's bounding box.** An SVG is read at its `viewBox`, a raster at its full canvas, and neither is trimmed to where the pixels actually are. So whatever margin a designer baked into the file **adds** to the padding configured per piece. A round logo exported inside a 2048×2048 PNG with 25% of its own air, generated at `adaptive: { padding: '18%' }`, ends up covering about 32% of the icon canvas, not 64%. If a mark comes out smaller than the numbers suggest, that is almost always why: crop the source or lower the padding.
+
+**The masters are sized to the run.** The source is rasterized once into two intermediate masters, and every piece scales down from them, so their resolution is the ceiling on output sharpness. Rather than a fixed size, `brand` measures the largest number of pixels any selected piece will ask for and builds the masters at exactly that. A default run reports it:
+
+```text
+  • Masters at 1024 px — the largest any selected piece asks for
+```
+
+Lower a padding and the figure rises with it (`--splash-padding 4` needs 1413 px), so output never goes soft against a fixed ceiling. Every destination is a reduction or the same size, never an upscale.
+
+The one case this cannot fix is a raster source that is simply too small: a 512-px PNG cannot produce a sharp 1024-px icon. Prefer SVG, or a PNG of at least 1024×1024.
+
+### Splash padding
+
+The 28 splash images (`default.png`, the 11 `res-*`, and the 16 iPhone launch images) share one rule: the logo is fitted into a square whose side is a share of the canvas's **shorter** side.
+
+Measuring against the shorter side is what lets a single number work across canvases as different as 1440×2560 and 800×480: at 800×480 the limit comes from the height, at 240×400 from the width, and the logo keeps the same visual weight in portrait and in landscape.
+
+| `androidSplash.padding` / `iosSplash.padding` | Logo | `default.png` (1440×2560) | `res-notlong-port-mdpi` (320×480) |
+| --- | --- | --- | --- |
+| `20%` | 60% of the shorter side | 864 px | 192 px |
+| `26%` (default) | 48% | 691 px | 153 px |
+| `30%` | 40% | 576 px | 128 px |
+| `35%` | 30% | 432 px | 96 px |
+
+The `26%` default is calibrated against the Titanium template itself: the Alloy logo in the stock `default.png` measures 665×488 px on a 1440×2560 canvas, so `26%` lands within 4% of the size Titanium ships.
+
+Before v7.13.0 none of this was configurable: `default.png` used a hardcoded box of 72% × 26% of its own canvas, and the `res-*` set a separate hardcoded 60%. Two rules for the same piece, neither adjustable.
+
+## Rounded non-icon artwork
+
+`brand.artworkCornerRadius` rounds artwork only in the 16 iPhone launch images, Android `default.png` plus its 11 qualifier variants, `MarketplaceArtworkFeature.png`, and `LaunchLogo.png`. A piece may override it with `cornerRadius`; `brand.splashCornerRadius` is an optional shared override for the two legacy splash pieces.
+
+```javascript
+brand: {
+  artworkCornerRadius: '22%',
+  iosSplash: { padding: '26%', cornerRadius: '18%' },
+  featureGraphic: { padding: '12%', cornerRadius: '20%' }
+}
+```
+
+Values are integer numbers or percentage strings from `0` through `50`, measured against the shorter side of the resized artwork. `0%` preserves the previous output byte for byte; `50%` makes square artwork circular and a wordmark capsule-shaped. Normal and `--dry-run` summaries report the effective padding and radius.
+
+Precedence is:
+
+- Feature Graphic / LaunchLogo: piece-specific flag → `--artwork-corner-radius` → piece config → `brand.artworkCornerRadius` → `0%`.
+- Legacy splashes: platform flag → `--splash-corner-radius` → `--artwork-corner-radius` → piece config → `brand.splashCornerRadius` → `brand.artworkCornerRadius` → `0%`.
+
+Store and launcher icons remain unmasked for platform processing. Despite their filenames, `iTunesConnect.png` and `MarketplaceArtwork.png` are app icons: Apple asks for square, unmasked artwork and Google Play applies its own rounded mask, so pre-rounding them would be wrong. `cornerRadius` is rejected in `DefaultIcon*`, `iTunesConnect.png`, `MarketplaceArtwork.png`, adaptive, legacy, and app icons, Android 12+ `splash_icon.png`, notification icons, and any other unsupported piece; invalid, fractional, negative, non-numeric, or greater-than-50 values also abort before files are written.
+
+### Adaptive icon padding
+
+Android's adaptive canvas is 108 dp. The mask leaves roughly 72 dp visible, and the **guaranteed** safe area is a 66 dp circle inscribed in it. What each padding means in those terms:
+
+| Padding | Logo | vs. the 66 dp safe circle | vs. the ~72 dp the mask shows |
+| --- | --- | --- | --- |
+| `15%` | 75.6 dp | outside | **outside** — clipped on any launcher |
+| `16%` | 73.4 dp | outside | **outside** |
+| `18%` | 69.1 dp | corners outside | inside — **the default** |
+| `19.44%` | 66.0 dp | exactly on it | inside |
+| `20%` | 64.8 dp | inside | inside — most conservative |
+
+`18%` sits between the guaranteed circle and the mask edge: a logo that carries its own margin never reaches those corners, which is why it is a safe default in practice. Raise it to `20%` if your mark runs edge to edge and you see clipping on a circular launcher.
+
+A useful visual check is the "corners" heuristic: imagine a circle inscribed in your 1024×1024 canvas with the given padding. If your logo's outermost corners fit inside that circle, you're safe on circular launchers (Pixel default, Oppo Android 15). If they poke out, they'll be clipped.
+
+The official Android spec floor is `19.44%` (108dp canvas, 66dp inscribed safe-zone circle). That is the theoretical worst-case for aggressive adaptive masks, which is why the adaptive default sits close to it.
+
+### Legacy icon padding
+
+Legacy `ic_launcher.png` does not go through the same adaptive mask, so it can usually run tighter. That is why the default for `brand.legacyIcon.padding` is `10%`.
+
+## See also
+
+- [App Icons & Branding](./app-branding.md) — the `brand` command, its pieces and config.
+- [`brand` command reference](./cli-commands.md#brand-command) — terse flag list, including every padding and corner-radius flag.