From a15adde3292b7d5ffbf3f82967da63848aa535d0 Mon Sep 17 00:00:00 2001 From: rdlabo Date: Sat, 22 Aug 2026 10:52:49 +0900 Subject: [PATCH] docs: organize theme guides --- README.md | 2 +- docs/special-markup.md | 5 +++ docs/using-ion-item-group.md | 66 +++++++++++------------------------- 3 files changed, 25 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index a5c9bd2..6a2db07 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A CSS/JS theme library that applies Material Design 3 design system to Ionic applications. -![Material Design 3 themed Ionic screens with updated components and navigation](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-md3/v1.1.0/screenshots/md3.png) +![Material Design 3 themed Ionic screens with updated components and navigation](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-md3/v2.0.0-1/screenshots/md3.png) DEMO is here: https://ionic-theme-md3.rdlabo.dev/ diff --git a/docs/special-markup.md b/docs/special-markup.md index 715bd91..1318461 100644 --- a/docs/special-markup.md +++ b/docs/special-markup.md @@ -36,6 +36,8 @@ Add `.button-square` when a button should use more squared corners. It works wit Add `.item-group-header` to an `ion-item-group` to create the centered icon, title, and description used at the top of the component demo pages. +This is an introductory group. Place regular list items in a separate `ion-item-group` that follows it. + ```html preview @@ -47,6 +49,9 @@ Add `.item-group-header` to an `ion-item-group` to create the centered icon, tit + + First item + ``` diff --git a/docs/using-ion-item-group.md b/docs/using-ion-item-group.md index c03e917..12c6552 100644 --- a/docs/using-ion-item-group.md +++ b/docs/using-ion-item-group.md @@ -2,60 +2,32 @@ title: Using ion-item-group --- -# Using `ion-item-group` with the MD3 theme +# Using `ion-item-group` in inset lists -The MD3 theme supports the same inset-list markup as `@rdlabo/ionic-theme-ios26`, so an application can share one template across Ionic modes. Add `ion-item-group` when you opt in to that shared pattern. +The MD3 theme uses the same inset-list structure as `@rdlabo/ionic-theme-ios26`, allowing one template to work across Ionic modes. When an `ion-list` uses `inset="true"`, wrap its items in `ion-item-group` and keep `ion-list-header` outside the group. -## When is `ion-item-group` required? +The examples use framework-neutral Web Component markup. In React or Vue, use the equivalent component and property syntax. -It is only required when both of the following conditions are met: - -- You have enabled the `inset` property on `ion-list` -- You import the iOS 26 package's optional `md-ion-list-inset.css` stylesheet - -When these conditions apply, wrap the list items—but not the list header—with `ion-item-group`. - -## Implementation Example - -```diff - - Label -+ - ... - ... -+ - +```html + + Connections + + ... + ... + + ``` -## Why is this change necessary? - -### Background: Challenges in iOS Design Reproduction - -By default in Ionic Framework, `ion-list` has a background color, and `ion-list-header` is treated as part of the list. However, with this structure, it's impossible to accurately reproduce **iOS's native design patterns**. - -![Inset list background comparison](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/why-ion-list-inset.png) +No wrapper is required for lists that do not use `inset="true"`. -### Solution: Background Color Separation +## Why the wrapper is required -To faithfully reproduce iOS design, this theme makes the following changes: - -- Set `ion-list` background color to transparent -- Delegate background color to `ion-item-group` - -This change allows `ion-list-header` to be treated as an independent element, achieving the native iOS appearance. - -## Using the Same Design with Material Design - -If you want to use the same design pattern with Material Design theme, import the following CSS: - -```css -@import '@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css'; -``` +The shared structure keeps `ion-list-header` separate from the item surface. This matches the iOS 26 layout while allowing MD3 to style the same markup without platform-specific templates. -This will apply the same `ion-item-group` pattern to the Material Design theme as well. +The theme therefore: -## Summary +- makes the inset `ion-list` background transparent; +- applies the item surface to `ion-item-group`; and +- leaves `ion-list-header` outside that surface. -- **Most cases**: You can use your existing Ionic code as-is -- **Specific conditions only**: `ion-item-group` is required when using the optional shared inset-list stylesheet -- **Purpose**: To accurately reproduce iOS 26's native design patterns +For two-line items and section-header groups, see [Special markup](./special-markup.md).