appdimens-dynamic

AppDimens Dynamic — project workflow

Library: io.github.bodenberg:appdimens-dynamic:3.1.5

DOC_REF (maintainers): bump every 3.1.5 URL in this skill and in library-map.md / reference.md together with the coordinate above on future releases.

Authoritative GitHub docs (ref 3.1.5):

• README.md — install, AppDimensProvider, DimenCache.invalidateOnConfigChange
• DOCUMENTATION/README.md — all strategies, decision flow
• DOCUMENTATION/COMPOSE-API-CONVENTIONS.md — Compose naming, facilitators, Plain chains, code parity
• DOCUMENTATION/resize.md — compose.resize / code.resize
• GUIDE-FOR-BEGINNERS.md — narrative walkthrough
• Examples: Compose · Kotlin Views · Java

Package map and strategy → doc index: library-map.md

---

Agent Preflight (run before any non-trivial edit)

1. Read library-map.md for package layout and strategy ↔ doc mapping.
2. For the specific packages/symbols you’ll touch: browse library/src/main/java/com/appdimens/dynamic/ on GitHub at 3.1.5, or use IDE “Download Sources” / “Navigate to Declaration” on the Maven artifact. For API detail, see DOCUMENTATION/index.md and per-package pages under DOCUMENTATION/KDOC/. Do not rely on memory.
3. Skim the upstream example that matches the user’s stack (links above). Restrict deep reading to relevant packages and call sites — full module audits only when explicitly requested.

Hard rule: never surface ignoreMultiWindows, *i, or *ia suffixes to users.

---

Phase 0 — Interactive Baseline

Ask questions one at a time. Wait for the answer before moving to the next step. Skip any already answered in the conversation.

0.1 UI Stack

Which surface is in scope?

Choice	Package family	Key note
Jetpack Compose	com.appdimens.dynamic.compose.*	16.sdp, scaledDp { }; needs AppDimensProvider for facilitators
Kotlin (Views)	com.appdimens.dynamic.code.*	DimenSdp.sdp(context, 16); outputs px for layout
Java (Views)	same code.* entry points	see ExampleActivity.java

Record: drives imports, AppDimensProvider need, and whether resize runs in compose.resize or code.resize.

→ Wait for answer, then ask 0.2.

0.2 Screen Metric Qualifier (DpQualifier)

Which axis should DpQualifier-aware APIs use? (Affects .sdpQualifier, .sdpScreen, scaled .sspRotate vs strategy-prefixed Sp rotates such as .asspRotate, and their code mirrors.)

• SMALL_WIDTH (default) — smallest-width (swDP) baseline; correct for most phone/tablet layouts.
• Explicit WIDTH / HEIGHT (or per-call-site mix) — when design requires width-dp or height-dp branching. Read COMPOSE-API-CONVENTIONS.md and DpQualifier KDoc before proposing thresholds.

Record before suggesting any .screen, .qualifier, rotate, or power-curve APIs.

→ Wait for answer, then ask 0.3.

0.3 Task Type

Disambiguate first — these are separate workflows:

• Scaling strategy = global dimension curve (sdp, percent, fluid, …) → Phase 1.
• Resize = constraint-based fit (autoResize*, ResizeBound) → Phase 3.

Ask which applies:

• Strategy selection only — also ask: manual (user picks after seeing options) or AI-proposed (you propose, user confirms)? Warn that automatic proposals are more error-prone on mixed form factors and resize-heavy UIs.
• Resize only — still complete 0.1, 0.2, and 0.4; go directly to Phase 3.
• Both — run Phase 1, then Phase 3.

If automatic strategy mode: confirm each major screen or module after proposing, before bulk edits.

→ Wait for answer, then ask 0.4.

0.4 Scope

Full migration (app-wide) or partial? For partial scope, list concrete paths or identifiers (files, packages, screens, composables, XML layouts, specific dimensions) before editing.

→ Wait for answer, then ask 0.5.

0.5 Acceptance Criteria

For each major screen or module, ask for plain-language criteria (e.g., “no clipped titles on foldable inner display”, “comfortable padding on 10-inch tablet”). Tie every recommendation explicitly to these.

→ Once answered, proceed to the relevant phase(s).

---

Phase 1 — Scaling Strategy Selection

Run only when Phase 0.3 includes strategy selection. Skip for resize-only tasks with unchanged surrounding curves.

Default: Scaled

compose.scaled / code.scaled — recommend this first. Linear scaling around a 300 dp reference on the chosen axis.

Variant	Typical use
.sdp	General spacing, padding, corner radii
.hdp	Vertical rhythm, row heights
.wdp	Width-driven columns
.ssp	Text; use hsp/wsp for axis variants
.sdpa / .hdpa	Very wide or tall screens where plain scaled is too aggressive or too conservative

In manual mode: present this default and ask which UI areas use it. Accept “everything scaled except …” rules.
In automatic mode: propose per screen, confirm before bulk edits.

Other Strategies

Use only when requirements or QA justify leaving scaled. Before recommending any strategy below, read its matching doc in DOCUMENTATION/ — see library-map.md § “Strategy → doc”. Pull trade-offs from that doc, not from memory.

Strategy	Role	Typically when	Not ideal when
Percent	Literal fraction of a screen axis	Sizes must track sw/w/h directly (hero = 90% w)	Only need “design at 300 dp” feel — use scaled
Power	Sublinear growth, softer on large screens	Large phones/tablets feel “too big” with linear	Need predictable linear mapping everywhere
Fluid	Band behavior between reference widths	Strong control inside a width band	One simple curve app-wide without band tuning
Auto	Breakpoint-style blend (linear + log past threshold)	Clear “phone vs tablet” knee in the curve	Need mathematically smooth everywhere
Diagonal	Curve on a diagonal screen metric	Ultrawide / non-standard aspect emphasis	Simple portrait phone layouts
Fill	Cover-like growth vs reference (“bold”)	Visual dominance on large canvas	Risk oversized touch targets without QA
Fit	Contain-like growth vs reference (conservative)	Prefer smaller on large screens	Need aggressive use of space on tablets
Interpolated	Piecewise curve between configured points	Hand-tuned points from design spec	No intermediate data — high maintenance
Logarithmic	Log-shaped curve, dampens growth	Strong dampening needed	Need linear proportional feel
Perimeter	Perimeter-style metric in formula	Designs keyed to “frame” perception	No such requirement
Density	Classic density-style scaling	Matching legacy dp-to-physical expectations	Want screen-shape-aware curves
Physical units	mm / cm / in helpers	Real-world sizing (rulers, print-like UI)	Most Material layout — use scaled instead
Resize	(not a global curve) Largest discrete step in [min,max] fitting constraints	Auto-fit text or boxes inside known max	Whole-screen proportional layout

---

Phase 2 — Implementation Rules

Apply regardless of strategy or UI stack:

1. Strategy isolation — compose.<strategy> and code.<strategy> do not cross-import. One strategy per calculation path.
2. AppDimensProvider — required for Compose facilitators like .sdpMode, .sdpScreen, .sspScreen (see README).
3. Config churn — if the Activity is not recreated on handled config changes (rotation, font scale, density, configChanges in manifest), consider DimenCache.invalidateOnConfigChange.
4. code hot paths — prefer Int/Float receivers for sdp/hdp/wdp to avoid boxing.
5. Nested Plain facilitators — use Dp/TextUnit alternates in *Plain chains to avoid double-scaling (README + COMPOSE-API-CONVENTIONS).

---

Phase 3 — Resize Work

Run when the user touches autoResize* APIs, ResizeBound, ResizeRangePx, or DimenResize.

Ask in order, waiting for each answer before continuing:

1. Element type — text (font size sweep, sp) or non-text component (heights, widths, square sizes, images, cards)?
2. Constraint source — Compose: must run inside BoxWithConstraints (max width/height in dp). Views/code: how is max px/dp obtained?
3. Expected behavior — fill to cap, shrink to fit, or prefer a size? Any min/max in dp, sp, axis percent (screen), or percent of inner box?
4. Bounds semantics — clarify ResizeBound.FixedDp / FixedSp / Percent (sw/w/h axis). For percent-in-container resize, clarify AutoResizePercentBasis (min/max side, width, height) and use autoResizeTextSpPercent (Compose) or fittingTextSpPercentPx (code). Remind: resolveToPx requires density > 0; invalid inputs are clamped (library KDoc).
5. Approach check — global proportional sizing across the screen is usually scaled/percent/fluid, not resize. Reserve resize for fit-to-container problems.

Reference: DOCUMENTATION/resize.md

---

Phase 4 — Execution Checklist

• Agent Preflight completed for touched symbols.
• Phase 0 answered: stack, DpQualifier baseline, task type (strategy / resize / both), scope, acceptance criteria.
• Scaled presented as default; other strategies have matching DOCUMENTATION/*.md opened and trade-offs cited.
• ignoreMultiWindows / *i / *ia not surfaced to user.
• Docs or KDoc read for anything beyond trivial one-liners.
• Diffs are small and reviewable; aligned with upstream example patterns.
• Build / lint the touched module if available.

---

Output Style

For every decision state: chosen strategy, package family (compose.* or code.*), axis (sdp vs hdp vs wdp), whether resize vs global scaling, and which acceptance criterion it satisfies. Prefer small, reviewable diffs aligned with existing project patterns.

This site is open source. Improve this page.