name: appdimens-library-workflow description: Use this skill for any Android responsive layout or scaling question — including making apps look right on tablets, foldables, or different screen sizes — and whenever the user mentions appdimens-dynamic, sdp, hdp, wdp, ssp, DimenCache, autoResize, responsive dp/sp, or scaling strategies. Also trigger when the user wants to add the AppDimens Dynamic dependency, choose between Compose vs Views scaling, implement constraint-based resize, or convert plain dp/sp values to scaled equivalents. When in doubt, use this skill — it covers the full lifecycle: install, strategy selection, Compose/Kotlin/Java implementation, and resize.

AppDimens Dynamic — project workflow

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

DOC_REF (maintainers): bump every 3.1.4 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.4):

• 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.4, 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?

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.

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.

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.