Skip to content

Commit cebf16e

Browse files
bodenbergbodenberg
committed
2.0.1
1 parent b3e093d commit cebf16e

File tree

5 files changed

+387
-15
lines changed

5 files changed

+387
-15
lines changed

‎DOCS/DOCS_QUICK_REFERENCE.md‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -25,21 +25,21 @@ What's your app type?
2525

2626
## 📊 13 Strategies at a Glance
2727

28-
| # | Strategy | Formula | Use Case | Score |
29-
|---|----------|---------|----------|-------|
30-
| 1 | **BALANCED** ⭐ | Hybrid linear-log | Multi-device (PRIMARY) | 93/100 |
31-
| 2 | LOGARITHMIC | `1 + k×ln(W/300)` | TV, max control | 88/100 |
32-
| 3 | POWER | `(W/300)^0.75` | General, configurable | 86/100 |
33-
| 4 | **DEFAULT** | `~97% linear + AR` | Phone-focused (SECONDARY) | 82/100 |
34-
| 5 | FLUID | `clamp(min, max)` | Typography | 78/100 |
35-
| 6 | AUTOSIZE 🆕 | Container-aware | Dynamic text | 78/100 |
36-
| 7 | FIT | `min(W/300, H/533)` | Games (letterbox) | 75/100 |
37-
| 8 | FILL | `max(W/300, H/533)` | Games (cover) | 73/100 |
38-
| 9 | DIAGONAL | `√(W²+H²)/611.63` | Physical size | 72/100 |
39-
| 10 | INTERPOLATED | `50% linear` | Moderate | 70/100 |
40-
| 11 | PERIMETER | `(W+H)/833` | W+H balance | 70/100 |
41-
| 12 | PERCENTAGE | `W/300` | Containers ONLY | 62/100 |
42-
| 13 | NONE | `x` | No scaling | 55/100 |
28+
| # | Strategy | Formula | AR Support | Use Case | Score |
29+
|---|----------|---------|------------|----------|-------|
30+
| 1 | **BALANCED** ⭐ | Hybrid linear-log | ✅ Yes | Multi-device (PRIMARY) | 93/100 |
31+
| 2 | LOGARITHMIC | `1 + k×ln(W/300)` | ✅ Yes | TV, max control | 88/100 |
32+
| 3 | POWER | `(W/300)^0.75` | ✅ Yes | General, configurable | 86/100 |
33+
| 4 | **DEFAULT** | `~97% linear + AR` | ✅ Yes | Phone-focused (SECONDARY) | 82/100 |
34+
| 5 | FLUID | `clamp(min, max)` | ⚙️ Opt-in | Typography | 78/100 |
35+
| 6 | AUTOSIZE 🆕 | Container-aware | ❌ No | Dynamic text | 78/100 |
36+
| 7 | FIT | `min(W/300, H/533)` | ❌ No | Games (letterbox) | 75/100 |
37+
| 8 | FILL | `max(W/300, H/533)` | ❌ No | Games (cover) | 73/100 |
38+
| 9 | DIAGONAL | `√(W²+H²)/611.63` | ❌ No | Physical size | 72/100 |
39+
| 10 | INTERPOLATED | `50% linear` | ✅ Yes | Moderate | 70/100 |
40+
| 11 | PERIMETER | `(W+H)/833` | ❌ No | W+H balance | 70/100 |
41+
| 12 | PERCENTAGE | `W/300` | ❌ No | Containers ONLY | 62/100 |
42+
| 13 | NONE | `x` | ❌ No | No scaling | 55/100 |
4343

4444
---
4545

@@ -152,6 +152,30 @@ FLUID: clamp(min, interpolate(W), max)
152152
| 720dp | 70dp ⭐ | 79dp | 115dp ❌ | Tablet |
153153
| 1080dp | 101dp | 94dp | 173dp ❌ | TV |
154154

155+
### 📐 Aspect Ratio (AR) Impact Comparison (48dp base)
156+
157+
**Devices with different aspect ratios:**
158+
159+
| Device | Resolution | AR | Strategy | Without AR | With AR | Impact |
160+
|--------|------------|-----|----------|------------|---------|---------|
161+
| **Phone (Standard)** | 360×640 | 1.78 | BALANCED | 57.6dp | 57.6dp | 0% (ref) |
162+
| | | | DEFAULT | 53.6dp | 53.6dp | 0% (ref) |
163+
| | | | LOGARITHMIC | 42.0dp | 42.0dp | 0% (ref) |
164+
| **Phone (Elongated)** | 360×800 | 2.22 | BALANCED | 57.6dp | 57.9dp | +0.5% |
165+
| | | | DEFAULT | 53.6dp | 54.2dp | +1.1% |
166+
| | | | LOGARITHMIC | 42.0dp | 42.2dp | +0.5% |
167+
| **Tablet (16:9)** | 720×1280 | 1.78 | BALANCED | 69.7dp | 69.7dp | 0% (ref) |
168+
| | | | DEFAULT | 78.7dp | 78.7dp | 0% (ref) |
169+
| | | | LOGARITHMIC | 67.2dp | 67.2dp | 0% (ref) |
170+
| **Tablet (Elongated)** | 720×1600 | 2.22 | BALANCED | 69.7dp | 70.1dp | +0.6% |
171+
| | | | DEFAULT | 78.7dp | 79.6dp | +1.1% |
172+
| | | | LOGARITHMIC | 67.2dp | 67.5dp | +0.4% |
173+
| **TV (16:9)** | 1080×1920 | 1.78 | BALANCED | 101.4dp | 101.4dp | 0% (ref) |
174+
| | | | DEFAULT | 93.6dp | 93.6dp | 0% (ref) |
175+
| | | | LOGARITHMIC | 85.3dp | 85.3dp | 0% (ref) |
176+
177+
> **Note:** AR=1.78 (16:9) is the reference, so AR adjustment is neutral (0%). Elongated screens (AR>1.78) get slight size increases (+0.5% to +1.1%), while wider screens (AR<1.78) get slight decreases.
178+
155179
---
156180

157181
## 🚀 Common Patterns

‎DOCS/EXAMPLES.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,168 @@ Text('Hello', style: TextStyle(fontSize: AppDimens.balanced(16).calculate(contex
8282
```
8383
{% endraw %}
8484

85+
### 1.2 Aspect Ratio (AR) Impact Examples
86+
87+
> **📐 Version 2.0:** Six strategies now support automatic aspect ratio compensation. Here are practical examples showing the impact.
88+
89+
#### Understanding AR
90+
91+
**What is Aspect Ratio?**
92+
- AR = max(width, height) / min(width, height)
93+
- Reference: 16:9 = 1.78 (neutral adjustment)
94+
- Modern phones: 18:9 to 21:9 = 2.0 to 2.33 (elongated)
95+
- Tablets: 4:3 to 16:10 = 1.33 to 1.6 (wider)
96+
97+
#### Example 1: Phone with Different Aspect Ratios
98+
99+
**Scenario:** A 48dp button on a 360dp width phone
100+
101+
**Standard Phone (360×640, 16:9 - AR=1.78):**
102+
```kotlin
103+
// Android
104+
val buttonHeight = 48.balanced().dp // Result: 57.6dp
105+
106+
// iOS
107+
let height = AppDimens.shared.balanced(48) // Result: 57.6pt
108+
109+
// Flutter
110+
final height = AppDimens.balanced(48).calculate(context) // Result: 57.6dp
111+
```
112+
113+
**Elongated Phone (360×800, 20:9 - AR=2.22):**
114+
```kotlin
115+
// Android
116+
val buttonHeight = 48.balanced().dp // Result: 57.9dp (+0.5%)
117+
118+
// iOS
119+
let height = AppDimens.shared.balanced(48) // Result: 57.9pt (+0.5%)
120+
121+
// Flutter
122+
final height = AppDimens.balanced(48).calculate(context) // Result: 57.9dp (+0.5%)
123+
```
124+
125+
**Visual Impact:**
126+
- Without AR: Button feels smaller on elongated screens
127+
- With AR: Slight size increase maintains visual weight
128+
- User perception: Consistent button appearance across devices
129+
130+
#### Example 2: Comparison Across Strategies
131+
132+
**Device:** Pixel 6 Pro (412×915, AR=2.22) vs Galaxy S21 (360×800, AR=2.22)
133+
134+
**48dp Button Height:**
135+
136+
| Strategy | Without AR | With AR | Difference |
137+
|----------|------------|---------|------------|
138+
| BALANCED | 65.9dp | 66.3dp | **+0.6%** |
139+
| DEFAULT | 61.3dp | 62.0dp | **+1.1%** (highest) |
140+
| LOGARITHMIC | 56.9dp | 57.1dp | **+0.4%** |
141+
| POWER | 61.4dp | 61.7dp | **+0.5%** |
142+
| INTERPOLATED | 60.5dp | 60.8dp | **+0.5%** |
143+
144+
#### Example 3: Foldable Device Handling
145+
146+
**Samsung Galaxy Z Fold 4:**
147+
- Folded (cover screen): 832×2268 (AR=2.73) - Very elongated
148+
- Unfolded (main screen): 1768×2208 (AR=1.25) - Almost square
149+
150+
```kotlin
151+
// Android
152+
@Composable
153+
fun AdaptiveButton() {
154+
val configuration = LocalConfiguration.current
155+
val isUnfolded = configuration.screenWidthDp > 600
156+
157+
Button(
158+
modifier = Modifier.height(48.balanced().dp)
159+
// Folded: ~75dp with AR adjustment
160+
// Unfolded: ~85dp with different AR
161+
) {
162+
Text("Adaptive Button", fontSize = 16.balanced().sp)
163+
}
164+
}
165+
```
166+
167+
#### Example 4: Multi-Window / Split Screen
168+
169+
**Scenario:** App in split-screen mode creates unusual aspect ratios
170+
171+
```kotlin
172+
// Android - Handling split screen
173+
@Composable
174+
fun SplitScreenAware() {
175+
val windowSize = currentWindowAdaptiveInfo().windowSizeClass
176+
177+
// In split screen: width=360dp, height=400dp, AR=1.11 (very wide)
178+
// AR adjustment: ×0.985 (-1.5% to compensate for unusual proportion)
179+
180+
Card(
181+
modifier = Modifier
182+
.width(300.percentageDp.dp) // No AR adjustment
183+
.padding(16.balanced().dp) // With AR adjustment
184+
) {
185+
Text(
186+
"AR-Aware Content",
187+
fontSize = 16.balanced().sp
188+
)
189+
}
190+
}
191+
```
192+
193+
#### Example 5: Disabling AR for Specific Cases
194+
195+
**FLUID strategy with manual AR control:**
196+
197+
```kotlin
198+
// Android
199+
val textSize = fluidSp(
200+
minValue = 14f,
201+
maxValue = 20f,
202+
applyAspectRatio = false // Disable AR for this specific element
203+
)
204+
205+
// iOS
206+
let size = AppDimens.shared.fluid(
207+
min: 14,
208+
max: 20,
209+
applyAspectRatio: false
210+
)
211+
212+
// Flutter
213+
final size = AppDimens.fluid(
214+
14,
215+
maxValue: 20,
216+
applyAspectRatio: false
217+
).calculate(context)
218+
```
219+
220+
#### Example 6: Real-World Impact
221+
222+
**Social Media Feed Card:**
223+
224+
```kotlin
225+
// Without AR awareness
226+
Card(
227+
modifier = Modifier
228+
.fillMaxWidth()
229+
.height(200.defaultDp) // Same height on all phones
230+
) {
231+
// On elongated phone: card looks "short" and "squashed"
232+
}
233+
234+
// With AR awareness
235+
Card(
236+
modifier = Modifier
237+
.fillMaxWidth()
238+
.height(200.defaultDp) // Slightly taller on elongated phones
239+
) {
240+
// On elongated phone (AR=2.22): ~202dp height (+1%)
241+
// Maintains visual proportion
242+
}
243+
```
244+
245+
**Key Takeaway:** AR compensation ensures visual consistency across the growing variety of screen shapes in modern devices (foldables, elongated phones, tablets, split-screen, multi-window).
246+
85247
---
86248

87249
## 2. Android Examples

‎DOCS/FORMULA_COMPARISON.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,17 @@ arAdj(AR) = 1 + k_AR × ln(AR / AR₀) [enabled by default]
147147
| 960dp | 88.3dp | **-42.5%** | Maximum control |
148148
| 1080dp | 100.9dp| **-41.6%** | TV-optimized |
149149

150+
**📐 Aspect Ratio Impact (48dp base):**
151+
152+
| Device | Resolution | AR | Without AR | With AR | Difference |
153+
|--------|------------|-----|------------|---------|------------|
154+
| Phone (Standard) | 360×640 | 1.78 | 57.6dp | 57.6dp | 0% (reference) |
155+
| Phone (Elongated) | 360×800 | 2.22 | 57.6dp | 57.9dp | **+0.5%** |
156+
| Phone (21:9) | 360×840 | 2.33 | 57.6dp | 58.0dp | **+0.7%** |
157+
| Tablet (Standard) | 720×1280 | 1.78 | 69.7dp | 69.7dp | 0% (reference) |
158+
| Tablet (Elongated) | 720×1600 | 2.22 | 69.7dp | 70.1dp | **+0.6%** |
159+
| TV (16:9) | 1080×1920 | 1.78 | 100.9dp | 100.9dp | 0% (reference) |
160+
150161
**When to Use:**
151162
- ✅ Multi-device apps (phones, tablets, TVs)
152163
- ✅ Social media, productivity, e-commerce
@@ -206,6 +217,17 @@ arAdj(AR) = 1 + k_AR × ln(AR / AR₀) [enabled by default]
206217
| 720dp | 67.2dp | **-41.7%**| -3.6% |
207218
| 1080dp | 75.8dp | **-56.1%**| -24.9% |
208219

220+
**📐 Aspect Ratio Impact (48dp base):**
221+
222+
| Device | Resolution | AR | Without AR | With AR | Difference |
223+
|--------|------------|-----|------------|---------|------------|
224+
| Phone (Standard) | 360×640 | 1.78 | 51.5dp | 51.5dp | 0% (reference) |
225+
| Phone (Elongated) | 360×800 | 2.22 | 51.5dp | 51.7dp | **+0.4%** |
226+
| Phone (21:9) | 360×840 | 2.33 | 51.5dp | 51.8dp | **+0.6%** |
227+
| Tablet (Standard) | 720×1280 | 1.78 | 67.2dp | 67.2dp | 0% (reference) |
228+
| Tablet (Elongated) | 720×1600 | 2.22 | 67.2dp | 67.5dp | **+0.4%** |
229+
| TV (16:9) | 1080×1920 | 1.78 | 75.8dp | 75.8dp | 0% (reference) |
230+
209231
**When to Use:**
210232
- ✅ TV applications (960dp+)
211233
- ✅ Very large tablets (840dp+)
@@ -257,6 +279,17 @@ arAdj(AR) = 1 + k_AR × ln(AR / AR₀) [enabled by default]
257279
| n = 0.80 | 82.3dp | **-28.5%**| Moderate |
258280
| n = 0.90 | 104.5dp| **-9.3%** | Aggressive |
259281

282+
**📐 Aspect Ratio Impact (48dp base, exponent=0.75):**
283+
284+
| Device | Resolution | AR | Without AR | With AR | Difference |
285+
|--------|------------|-----|------------|---------|------------|
286+
| Phone (Standard) | 360×640 | 1.78 | 53.6dp | 53.6dp | 0% (reference) |
287+
| Phone (Elongated) | 360×800 | 2.22 | 53.6dp | 53.8dp | **+0.4%** |
288+
| Phone (21:9) | 360×840 | 2.33 | 53.6dp | 53.9dp | **+0.6%** |
289+
| Tablet (Standard) | 720×1280 | 1.78 | 76.8dp | 76.8dp | 0% (reference) |
290+
| Tablet (Elongated) | 720×1600 | 2.22 | 76.8dp | 77.1dp | **+0.4%** |
291+
| TV (16:9) | 1080×1920 | 1.78 | 94.0dp | 94.0dp | 0% (reference) |
292+
260293
**When to Use:**
261294
- ✅ General-purpose applications
262295
- ✅ When configurability is needed
@@ -306,6 +339,19 @@ AR = aspect ratio
306339
| 720dp | 79.2dp | **-31.3%**| +13.6% |
307340
| 1080dp | 94.0dp | **-45.6%**| -6.8% |
308341

342+
**📐 Aspect Ratio Impact (48dp base):**
343+
344+
| Device | Resolution | AR | Without AR | With AR | Difference |
345+
|--------|------------|-----|------------|---------|------------|
346+
| Phone (Standard) | 360×640 | 1.78 | 53.6dp | 53.6dp | 0% (reference) |
347+
| Phone (Elongated) | 360×800 | 2.22 | 53.6dp | 54.2dp | **+1.1%** |
348+
| Phone (21:9) | 360×840 | 2.33 | 53.6dp | 54.4dp | **+1.5%** |
349+
| Tablet (Standard) | 720×1280 | 1.78 | 78.7dp | 78.7dp | 0% (reference) |
350+
| Tablet (Elongated) | 720×1600 | 2.22 | 78.7dp | 79.6dp | **+1.1%** |
351+
| TV (16:9) | 1080×1920 | 1.78 | 93.6dp | 93.6dp | 0% (reference) |
352+
353+
> **Note:** DEFAULT has the highest AR sensitivity among all strategies, making it most responsive to aspect ratio variations.
354+
309355
**When to Use:**
310356
- ✅ Phone-focused apps (320-480dp)
311357
- ✅ Backward compatibility with v1.x
@@ -417,6 +463,15 @@ arAdj(AR) = 1 + k_AR × ln(AR / AR₀) [enabled by default]
417463
**Scoring:**
418464
- Overall: **70/100** **#7 Moderate Scaling**
419465

466+
**📐 Aspect Ratio Impact (48dp base):**
467+
468+
| Device | Resolution | AR | Without AR | With AR | Difference |
469+
|--------|------------|-----|------------|---------|------------|
470+
| Phone (Standard) | 360×640 | 1.78 | 52.8dp | 52.8dp | 0% (reference) |
471+
| Phone (Elongated) | 360×800 | 2.22 | 52.8dp | 53.0dp | **+0.4%** |
472+
| Tablet (Standard) | 720×1280 | 1.78 | 81.6dp | 81.6dp | 0% (reference) |
473+
| Tablet (Elongated) | 720×1600 | 2.22 | 81.6dp | 82.0dp | **+0.5%** |
474+
420475
**When to Use:**
421476
- ✅ Medium screens (phablets, small tablets)
422477
- ✅ When BALANCED is too conservative

0 commit comments

Comments
 (0)