kiso 0.3.0.pre → 0.4.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ae0456b44e65c4a1f0c0fc7a0fb854daca4af8bf933d13d0fa2a3e78dc0b5d
-  data.tar.gz: 5dad006edca36a6d23822274557de73667eb8bd8aa69aa575037859ed1983742
+  metadata.gz: ce3df9a9c977207d60d0253493414495486682817829e7afb9c3ea4f856756b2
+  data.tar.gz: ea280bd1479c2bfe90a8fdd3fe597efe1a88c427031f096b24536a02c3558899
 SHA512:
-  metadata.gz: 490e5777fbc1fd030736c6c7866b3e39855699d7f71be28af41c9fc6bb2cbd7fd6b793d9d302e35886908ce663ddcc98e171ffd1c3419eebf8c6577073276c12
-  data.tar.gz: caa47f1734d26450d7163108cefa70438d75e8ef1201ffc1b4123eb4e5bb5e22aa5f7b545fddad657235d79d18e62aacb05818b6f0aa87922baa20c2d3d66bbb
+  metadata.gz: 34279aa5743e7baf516464c98ab5984de8edace8789646cb2277270ba5320f8b5763849141a4c2ddeee85f42d23c21638bcc4d11dcb0dd0f34792b09c8efa217
+  data.tar.gz: 8da0d3477b660de7fc174da7a7a1608e39783bd763b428f570beaf4385b301fa5eb9105384a87ff61791d09bab655ad3882c148f39d93f6c8402149c0fbfbac8

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0.pre] - 2026-03-08
+
+### Added
+
+- Layout component family: App, Container (4 size variants), Header, Footer, Main
+- Page component family: Page (grid with sidebars), PageHeader, PageBody, PageSection, PageGrid, PageCard (4 variants)
+- `appui()` helper for host app components with `app/themes/` and `app/views/components/`
+- `kiso:framework_component` generator for scaffolding engine components
+- `kiso:component` generator for scaffolding host app components
+- Theme presets: `apply_preset(:rounded)` and `apply_preset(:sharp)`
+- 5 OKLCH color palettes (zinc, blue, green, orange, violet)
+- i18n support: all component strings use `t()` with `config/locales/en.yml`
+- [Building Your Own Components](/guide/building-components) guide — how to wrap Kiso components with domain logic and build standalone components with `appui()`, themes, and sub-parts
+- [Detailed release notes](/releases/batch-merge) with upgrade guide and examples for all new features
+
 ## [0.3.0.pre] - 2026-03-03
 
 ### Added
@@ -85,7 +100,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Lookbook component previews
 - Bridgetown documentation site
 
-[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.3.0.pre...HEAD
+[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.4.0.pre...HEAD
+[0.4.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.0.pre
 [0.3.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.3.0.pre
 [0.2.2.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.2.pre
 [0.2.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.1.pre

data/README.md

@@ -1,6 +1,19 @@
-# Kiso 基礎
-
-UI components for Rails. Built on ERB, Tailwind CSS, and Hotwire.
+<p align="center">
+  <a href="https://kisoui.com">
+    <img src="brand/svg/logo-horizontal-color.svg" width="280" alt="Kiso">
+  </a>
+</p>
+
+<p align="center">
+  UI components for Rails. Built on ERB, Tailwind CSS, and Hotwire.
+</p>
+
+<p align="center">
+  <a href="https://kisoui.com">Docs</a> ·
+  <a href="https://lookbook.kisoui.com">Lookbook</a> ·
+  <a href="https://github.com/steveclarke/kiso/discussions">Discussions</a> ·
+  <a href="https://discord.gg/aMshcWAW">Discord</a>
+</p>
 
 Add one gem and get badges, buttons, cards, alerts, and more. They all work with screen readers and dark mode.
 

data/app/assets/tailwind/kiso/engine.css

@@ -16,7 +16,8 @@
    Count carefully — wrong paths fail SILENTLY (classes just won't generate). */
 @source "../../../views";              /* → app/views              */
 @source "../../../helpers";            /* → app/helpers            */
-@source "../../../../lib/kiso/themes"; /* → lib/kiso/themes        */
+@source "../../../../lib/kiso/themes";  /* → lib/kiso/themes        */
+@source "../../../../lib/kiso/presets"; /* → lib/kiso/presets       */
 
 /* === Geist Font (by Vercel) ===
    Self-hosted variable fonts — no CDN dependency.
@@ -56,7 +57,7 @@
 
 @theme {
   /* Brand / action colors */
-  --color-primary: var(--color-sky-600);
+  --color-primary: var(--color-rose-500);
   --color-primary-foreground: white;
 
   --color-secondary: var(--color-teal-600);
@@ -99,7 +100,7 @@
    Redefine tokens under .dark — components never use dark: prefixes. */
 
 .dark {
-  --color-primary: var(--color-blue-400);
+  --color-primary: var(--color-rose-400);
   --color-primary-foreground: var(--color-zinc-950);
 
   --color-secondary: var(--color-teal-400);

data/app/assets/tailwind/kiso/palettes/blue.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Blue
+   A professional blue palette — classic SaaS/enterprise feel.
+   Based on shadcn/ui's Blue theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "kiso/palettes/blue.css";
+     2. Add to your HTML: <html data-palette="blue"> or <body data-palette="blue">
+*/
+
+[data-palette="blue"] {
+  /* Brand / action colors — vibrant blue */
+  --color-primary: oklch(0.488 0.243 264.376);
+  --color-primary-foreground: oklch(0.97 0.014 254.604);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — slate-tinted neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.13 0.028 261.692);
+
+  --color-muted: oklch(0.967 0.003 264.542);
+  --color-muted-foreground: oklch(0.551 0.027 264.364);
+
+  --color-accent: oklch(0.967 0.003 264.542);
+  --color-accent-foreground: oklch(0.21 0.034 264.665);
+
+  --color-inverted: oklch(0.21 0.034 264.665);
+  --color-inverted-foreground: oklch(0.985 0.002 247.839);
+  --color-elevated: oklch(0.967 0.003 264.542);
+  --color-accented: oklch(0.707 0.022 261.325);
+
+  --color-border: oklch(0.928 0.006 264.531);
+  --color-border-accented: oklch(0.707 0.022 261.325);
+
+  --color-ring: oklch(0.488 0.243 264.376);
+}
+
+.dark [data-palette="blue"],
+[data-palette="blue"].dark {
+  --color-primary: oklch(0.42 0.18 266);
+  --color-primary-foreground: oklch(0.97 0.014 254.604);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.13 0.028 261.692);
+  --color-foreground: oklch(0.985 0.002 247.839);
+
+  --color-muted: oklch(0.278 0.033 256.848);
+  --color-muted-foreground: oklch(0.707 0.022 261.325);
+
+  --color-accent: oklch(0.278 0.033 256.848);
+  --color-accent-foreground: oklch(0.985 0.002 247.839);
+
+  --color-inverted: oklch(0.985 0.002 247.839);
+  --color-inverted-foreground: oklch(0.21 0.034 264.665);
+  --color-elevated: oklch(0.278 0.033 256.848);
+  --color-accented: oklch(0.551 0.027 264.364);
+
+  --color-border: oklch(0.278 0.033 256.848);
+  --color-border-accented: oklch(0.551 0.027 264.364);
+
+  --color-ring: oklch(0.488 0.243 264.376);
+}

data/app/assets/tailwind/kiso/palettes/green.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Green
+   A fresh, natural green palette — great for eco, health, or finance apps.
+   Based on shadcn/ui's Green theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "kiso/palettes/green.css";
+     2. Add to your HTML: <html data-palette="green"> or <body data-palette="green">
+*/
+
+[data-palette="green"] {
+  /* Brand / action colors — vivid green */
+  --color-primary: oklch(0.648 0.2 131.684);
+  --color-primary-foreground: oklch(0.986 0.031 120.757);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — zinc neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.141 0.005 285.823);
+
+  --color-muted: oklch(0.967 0.001 286.375);
+  --color-muted-foreground: oklch(0.552 0.016 285.938);
+
+  --color-accent: oklch(0.967 0.001 286.375);
+  --color-accent-foreground: oklch(0.21 0.006 285.885);
+
+  --color-inverted: oklch(0.21 0.006 285.885);
+  --color-inverted-foreground: oklch(0.985 0 0);
+  --color-elevated: oklch(0.967 0.001 286.375);
+  --color-accented: oklch(0.705 0.015 286.067);
+
+  --color-border: oklch(0.92 0.004 286.32);
+  --color-border-accented: oklch(0.705 0.015 286.067);
+
+  --color-ring: oklch(0.648 0.2 131.684);
+}
+
+.dark [data-palette="green"],
+[data-palette="green"].dark {
+  --color-primary: oklch(0.648 0.2 131.684);
+  --color-primary-foreground: oklch(0.986 0.031 120.757);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.141 0.005 285.823);
+  --color-foreground: oklch(0.985 0 0);
+
+  --color-muted: oklch(0.274 0.006 286.033);
+  --color-muted-foreground: oklch(0.705 0.015 286.067);
+
+  --color-accent: oklch(0.274 0.006 286.033);
+  --color-accent-foreground: oklch(0.985 0 0);
+
+  --color-inverted: oklch(0.985 0 0);
+  --color-inverted-foreground: oklch(0.21 0.006 285.885);
+  --color-elevated: oklch(0.274 0.006 286.033);
+  --color-accented: oklch(0.552 0.016 285.938);
+
+  --color-border: oklch(0.274 0.006 286.033);
+  --color-border-accented: oklch(0.552 0.016 285.938);
+
+  --color-ring: oklch(0.648 0.2 131.684);
+}

data/app/assets/tailwind/kiso/palettes/orange.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Orange
+   A warm, energetic palette — great for creative, food, or community apps.
+   Based on shadcn/ui's Orange theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "kiso/palettes/orange.css";
+     2. Add to your HTML: <html data-palette="orange"> or <body data-palette="orange">
+*/
+
+[data-palette="orange"] {
+  /* Brand / action colors — warm orange */
+  --color-primary: oklch(0.646 0.222 41.116);
+  --color-primary-foreground: oklch(0.98 0.016 73.684);
+
+  --color-secondary: oklch(0.97 0.001 106.424);
+  --color-secondary-foreground: oklch(0.216 0.006 56.043);
+
+  /* Surface tokens — warm stone neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.147 0.004 49.25);
+
+  --color-muted: oklch(0.97 0.001 106.424);
+  --color-muted-foreground: oklch(0.553 0.013 58.071);
+
+  --color-accent: oklch(0.97 0.001 106.424);
+  --color-accent-foreground: oklch(0.216 0.006 56.043);
+
+  --color-inverted: oklch(0.216 0.006 56.043);
+  --color-inverted-foreground: oklch(0.985 0.001 106.423);
+  --color-elevated: oklch(0.97 0.001 106.424);
+  --color-accented: oklch(0.709 0.01 56.259);
+
+  --color-border: oklch(0.923 0.003 48.717);
+  --color-border-accented: oklch(0.709 0.01 56.259);
+
+  --color-ring: oklch(0.646 0.222 41.116);
+}
+
+.dark [data-palette="orange"],
+[data-palette="orange"].dark {
+  --color-primary: oklch(0.705 0.213 47.604);
+  --color-primary-foreground: oklch(0.98 0.016 73.684);
+
+  --color-secondary: oklch(0.268 0.007 34.298);
+  --color-secondary-foreground: oklch(0.985 0.001 106.423);
+
+  --color-background: oklch(0.147 0.004 49.25);
+  --color-foreground: oklch(0.985 0.001 106.423);
+
+  --color-muted: oklch(0.268 0.007 34.298);
+  --color-muted-foreground: oklch(0.709 0.01 56.259);
+
+  --color-accent: oklch(0.268 0.007 34.298);
+  --color-accent-foreground: oklch(0.985 0.001 106.423);
+
+  --color-inverted: oklch(0.985 0.001 106.423);
+  --color-inverted-foreground: oklch(0.216 0.006 56.043);
+  --color-elevated: oklch(0.268 0.007 34.298);
+  --color-accented: oklch(0.553 0.013 58.071);
+
+  --color-border: oklch(0.268 0.007 34.298);
+  --color-border-accented: oklch(0.553 0.013 58.071);
+
+  --color-ring: oklch(0.705 0.213 47.604);
+}

data/app/assets/tailwind/kiso/palettes/violet.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Violet
+   A rich, creative purple palette — great for design tools or premium brands.
+   Based on shadcn/ui's Violet theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "kiso/palettes/violet.css";
+     2. Add to your HTML: <html data-palette="violet"> or <body data-palette="violet">
+*/
+
+[data-palette="violet"] {
+  /* Brand / action colors — vivid violet */
+  --color-primary: oklch(0.541 0.281 293.009);
+  --color-primary-foreground: oklch(0.969 0.016 293.756);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens — gray neutrals */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.13 0.028 261.692);
+
+  --color-muted: oklch(0.967 0.003 264.542);
+  --color-muted-foreground: oklch(0.551 0.027 264.364);
+
+  --color-accent: oklch(0.967 0.003 264.542);
+  --color-accent-foreground: oklch(0.21 0.034 264.665);
+
+  --color-inverted: oklch(0.21 0.034 264.665);
+  --color-inverted-foreground: oklch(0.985 0.002 247.839);
+  --color-elevated: oklch(0.967 0.003 264.542);
+  --color-accented: oklch(0.707 0.022 261.325);
+
+  --color-border: oklch(0.928 0.006 264.531);
+  --color-border-accented: oklch(0.707 0.022 261.325);
+
+  --color-ring: oklch(0.541 0.281 293.009);
+}
+
+.dark [data-palette="violet"],
+[data-palette="violet"].dark {
+  --color-primary: oklch(0.606 0.25 292.717);
+  --color-primary-foreground: oklch(0.969 0.016 293.756);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.13 0.028 261.692);
+  --color-foreground: oklch(0.985 0.002 247.839);
+
+  --color-muted: oklch(0.278 0.033 256.848);
+  --color-muted-foreground: oklch(0.707 0.022 261.325);
+
+  --color-accent: oklch(0.278 0.033 256.848);
+  --color-accent-foreground: oklch(0.985 0.002 247.839);
+
+  --color-inverted: oklch(0.985 0.002 247.839);
+  --color-inverted-foreground: oklch(0.21 0.034 264.665);
+  --color-elevated: oklch(0.278 0.033 256.848);
+  --color-accented: oklch(0.551 0.027 264.364);
+
+  --color-border: oklch(0.278 0.033 256.848);
+  --color-border-accented: oklch(0.551 0.027 264.364);
+
+  --color-ring: oklch(0.606 0.25 292.717);
+}

data/app/assets/tailwind/kiso/palettes/zinc.css

@@ -0,0 +1,65 @@
+/* Kiso Color Palette: Zinc
+   A neutral, cool-toned palette using the Zinc scale.
+   Based on shadcn/ui's Zinc theme with OKLCH color values.
+
+   Usage:
+     1. Import in your CSS: @import "kiso/palettes/zinc.css";
+     2. Add to your HTML: <html data-palette="zinc"> or <body data-palette="zinc">
+*/
+
+[data-palette="zinc"] {
+  /* Brand / action colors — zinc primary (near-black in light, near-white in dark) */
+  --color-primary: oklch(0.21 0.006 285.885);
+  --color-primary-foreground: oklch(0.985 0 0);
+
+  --color-secondary: oklch(0.967 0.001 286.375);
+  --color-secondary-foreground: oklch(0.21 0.006 285.885);
+
+  /* Surface tokens */
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.141 0.005 285.823);
+
+  --color-muted: oklch(0.967 0.001 286.375);
+  --color-muted-foreground: oklch(0.552 0.016 285.938);
+
+  --color-accent: oklch(0.967 0.001 286.375);
+  --color-accent-foreground: oklch(0.21 0.006 285.885);
+
+  --color-inverted: oklch(0.21 0.006 285.885);
+  --color-inverted-foreground: oklch(0.985 0 0);
+  --color-elevated: oklch(0.967 0.001 286.375);
+  --color-accented: oklch(0.705 0.015 286.067);
+
+  --color-border: oklch(0.92 0.004 286.32);
+  --color-border-accented: oklch(0.705 0.015 286.067);
+
+  --color-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark [data-palette="zinc"],
+[data-palette="zinc"].dark {
+  --color-primary: oklch(0.92 0.004 286.32);
+  --color-primary-foreground: oklch(0.21 0.006 285.885);
+
+  --color-secondary: oklch(0.274 0.006 286.033);
+  --color-secondary-foreground: oklch(0.985 0 0);
+
+  --color-background: oklch(0.141 0.005 285.823);
+  --color-foreground: oklch(0.985 0 0);
+
+  --color-muted: oklch(0.274 0.006 286.033);
+  --color-muted-foreground: oklch(0.705 0.015 286.067);
+
+  --color-accent: oklch(0.274 0.006 286.033);
+  --color-accent-foreground: oklch(0.985 0 0);
+
+  --color-inverted: oklch(0.985 0 0);
+  --color-inverted-foreground: oklch(0.21 0.006 285.885);
+  --color-elevated: oklch(0.274 0.006 286.033);
+  --color-accented: oklch(0.552 0.016 285.938);
+
+  --color-border: oklch(0.274 0.006 286.033);
+  --color-border-accented: oklch(0.552 0.016 285.938);
+
+  --color-ring: oklch(0.552 0.016 285.938);
+}

data/app/helpers/kiso/app_component_helper.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Kiso
+  # View helpers for rendering host app components.
+  #
+  # Mirrors {ComponentHelper#kui} but resolves partials from
+  # +app/views/components/+ and themes from +AppThemes::+.
+  # No global config layer — host apps own the source directly.
+  #
+  # Included in all views automatically by {Engine}.
+  module AppComponentHelper
+    # Renders a host app component partial.
+    #
+    # Components live in +app/views/components/+. Sub-parts are nested
+    # in a directory matching the parent component name.
+    #
+    # @param component [Symbol] the component name (e.g. +:pricing_card+)
+    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
+    # @param collection [Array, nil] renders the partial once per item when present
+    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed by sub-part name.
+    #   For parent components, the hash is pushed onto a context stack so sub-parts
+    #   inherit overrides automatically. For self-rendering components, the hash is
+    #   also passed as a local so the partial can apply overrides to internally
+    #   rendered elements.
+    # @param kwargs [Hash] locals passed to the partial (e.g. +css_classes:+)
+    # @yield optional block for component content
+    # @return [ActiveSupport::SafeBuffer] rendered HTML
+    #
+    # @example Render a pricing card
+    #   appui(:pricing_card) { "Content" }
+    #
+    # @example Render a pricing card with sub-parts
+    #   appui(:pricing_card) do
+    #     appui(:pricing_card, :header) { "Header" }
+    #   end
+    #
+    # @example Render with per-slot overrides
+    #   appui(:pricing_card, ui: { header: "p-8" }) do
+    #     appui(:pricing_card, :header) { "Header" }
+    #   end
+    #
+    # @example Render a collection
+    #   appui(:pricing_card, collection: @plans)
+    def appui(component, part = nil, collection: nil, ui: nil, **kwargs, &block)
+      kiso_render_component(
+        component, part,
+        path_prefix: "components",
+        collection: collection, ui: ui, merge_global_ui: false,
+        **kwargs, &block
+      )
+    end
+  end
+end

data/app/helpers/kiso/component_helper.rb

@@ -11,6 +11,11 @@ module Kiso
     # @param component [Symbol] the component name (e.g. +:badge+, +:card+)
     # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
     # @param collection [Array, nil] renders the partial once per item when present
+    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed by sub-part name.
+    #   For parent components, the hash is pushed onto a context stack so sub-parts
+    #   inherit overrides automatically. For self-rendering components, the hash is
+    #   also passed as a local so the partial can apply overrides to internally
+    #   rendered elements.
     # @param kwargs [Hash] locals passed to the partial (e.g. +color:+, +variant:+, +css_classes:+)
     # @yield optional block for component content
     # @return [ActiveSupport::SafeBuffer] rendered HTML
@@ -18,33 +23,25 @@ module Kiso
     # @example Render a badge
     #   kui(:badge, color: :success, variant: :soft) { "Active" }
     #
-    # @example Render a card sub-part
-    #   kui(:card, :header) { "Title" }
+    # @example Render a card with per-slot overrides
+    #   kui(:card, ui: { header: "p-8", title: "text-xl" }) do
+    #     kui(:card, :header) do
+    #       kui(:card, :title) { "Dashboard" }
+    #     end
+    #   end
+    #
+    # @example Render an alert with inner element overrides
+    #   kui(:alert, icon: "info", ui: { close: "opacity-50" })
     #
     # @example Render a collection
     #   kui(:badge, collection: @tags)
-    def kui(component, part = nil, collection: nil, **kwargs, &block)
-      path = if part
-        "kiso/components/#{component}/#{part}"
-      else
-        "kiso/components/#{component}"
-      end
-
-      # Prevent yield from bubbling up the ERB rendering chain when no block
-      # is passed. Without this, partials that use `capture { yield }.presence`
-      # to support optional block overrides (e.g., toggle/collapse/separator)
-      # would have their `yield` bubble through nested content_tag blocks all
-      # the way to the layout's `<%= yield %>`, capturing the entire page
-      # template content. An explicit empty proc gives `yield` something to
-      # call, returning empty string → `.presence` returns nil → default
-      # content renders correctly.
-      block ||= proc {}
-
-      if collection
-        render partial: path, collection: collection, locals: kwargs, &block
-      else
-        render path, **kwargs, &block
-      end
+    def kui(component, part = nil, collection: nil, ui: nil, **kwargs, &block)
+      kiso_render_component(
+        component, part,
+        path_prefix: "kiso/components",
+        collection: collection, ui: ui, merge_global_ui: true,
+        **kwargs, &block
+      )
     end
 
     # Prepares +component_options+ for use with +content_tag+.
@@ -72,5 +69,94 @@ module Kiso
 
       (component_options.delete(:data) || {}).merge(slot: slot, **data_attrs)
     end
+
+    private
+
+    # Shared rendering pipeline for both kui() and appui().
+    #
+    # @param component [Symbol] the component name
+    # @param part [Symbol, nil] optional sub-part name
+    # @param path_prefix [String] partial path prefix (e.g. "kiso/components" or "components")
+    # @param collection [Array, nil] renders the partial once per item when present
+    # @param ui [Hash, nil] per-slot class overrides
+    # @param merge_global_ui [Boolean] whether to merge global config ui layer
+    # @param kwargs [Hash] locals passed to the partial
+    # @param block [Proc] optional block for component content
+    # @return [ActiveSupport::SafeBuffer] rendered HTML
+    def kiso_render_component(component, part, path_prefix:, collection:, ui:, merge_global_ui: true, **kwargs, &block)
+      path = if part
+        "#{path_prefix}/#{component}/#{part}"
+      else
+        "#{path_prefix}/#{component}"
+      end
+
+      # Prevent yield from bubbling up the ERB rendering chain when no block
+      # is passed. Without this, partials that use `capture { yield }.presence`
+      # to support optional block overrides (e.g., toggle/collapse/separator)
+      # would have their `yield` bubble through nested content_tag blocks all
+      # the way to the layout's `<%= yield %>`, capturing the entire page
+      # template content. An explicit empty proc gives `yield` something to
+      # call, returning empty string → `.presence` returns nil → default
+      # content renders correctly.
+      block ||= proc {}
+
+      if part
+        # Sub-part: merge slot override from parent's ui context
+        parent_ui = kiso_current_ui(component)
+        if (slot_classes = parent_ui[part].presence)
+          existing = kwargs[:css_classes] || ""
+          kwargs[:css_classes] = existing.blank? ? slot_classes : "#{existing} #{slot_classes}"
+        end
+
+        # Forward ui: to sub-part partial when explicitly provided
+        kwargs[:ui] = ui if ui
+
+        if collection
+          render partial: path, collection: collection, locals: kwargs, &block
+        else
+          render path, **kwargs, &block
+        end
+      else
+        # Parent component: merge global ui config with instance ui (or use instance ui directly)
+        merged_ui = if merge_global_ui
+          kiso_merge_ui_layers(component, ui)
+        else
+          ui || {}
+        end
+        has_ui = merged_ui.present?
+
+        # Push context for composed sub-parts to read (skip when empty)
+        kiso_push_ui_context(component, merged_ui) if has_ui
+        begin
+          locals = has_ui ? kwargs.merge(ui: merged_ui) : kwargs
+
+          if collection
+            render partial: path, collection: collection, locals: locals, &block
+          else
+            render path, **locals, &block
+          end
+        ensure
+          kiso_pop_ui_context(component) if has_ui
+        end
+      end
+    end
+
+    # Merge global config ui overrides with instance ui overrides.
+    # Global config is Layer 2, instance +ui:+ is Layer 3.
+    #
+    # @param component [Symbol] the component name
+    # @param instance_ui [Hash, nil] per-instance ui overrides
+    # @return [Hash{Symbol => String}] merged ui hash
+    def kiso_merge_ui_layers(component, instance_ui)
+      global_ui = Kiso.config.theme.dig(component, :ui)
+      return instance_ui || {} if global_ui.nil? || global_ui.empty?
+      return global_ui if instance_ui.nil? || instance_ui.empty?
+
+      # Instance wins. For slots in both, concatenate — tailwind_merge
+      # resolves conflicts when .render(class:) is called.
+      global_ui.merge(instance_ui) do |_slot, global_classes, instance_classes|
+        "#{global_classes} #{instance_classes}"
+      end
+    end
   end
 end