docs: require file-local SwiftUI previews

plugins/agent-portability-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-portability-skills",
-  "version": "8.5.3",
+  "version": "8.5.4",
   "description": "Maintainer skills for Socket-owned agent skill portability, Codex plugin surfaces, and host adapter guidance.",
   "author": {
     "name": "Gale",

plugins/agent-portability-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-portability-skills-maintenance"
-version = "8.5.3"
+version = "8.5.4"
 description = "Maintainer-only Python tooling baseline for Agent Portability Skills."
 requires-python = ">=3.11"
 dependencies = []

plugins/agentdeck/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentdeck",
-  "version": "8.5.3",
+  "version": "8.5.4",
   "description": "Local Codex runtime utilities for thread, hook, and app-server workflows.",
   "author": {
     "name": "Gale",

plugins/android-dev-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "android-dev-skills",
-  "version": "8.5.3",
+  "version": "8.5.4",
   "description": "Android, Kotlin, Java, Gradle, Android Gradle Plugin, testing, lint, UI implementation, and release-readiness workflow skills.",
   "author": {
     "name": "Gale",

plugins/apple-dev-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-dev-skills",
-  "version": "8.5.3",
+  "version": "8.5.4",
   "description": "Apple development workflows for Codex, including media and audio repair, XcodeGen migration, Xcode coding intelligence, SwiftUI animation and architecture, Core Animation, Apple typography, SF Symbols, AppKit architecture, Icon Composer app icons, Safari extensions, DeviceCheck/App Attest, Swift OpenAPI clients, and DocC authoring guidance.",
   "author": {
     "name": "Gale",

plugins/apple-dev-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "apple-dev-skills-maintainer"
-version = "8.5.3"
+version = "8.5.4"
 description = "Maintainer tooling for the apple-dev-skills repository"
 requires-python = ">=3.10"
 dependencies = []

plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/apple-typography-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/avaudio-engine-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/avfaudio-session-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/avfoundation-media-pipeline-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/bootstrap-swift-package/assets/AGENTS.md

@@ -98,6 +98,8 @@
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/assets/AGENTS.md

@@ -19,6 +19,8 @@
 - Keep data flow straight and dependency direction unidirectional.
 - Treat the `.xcworkspace` or `.xcodeproj` as the source of truth for app integration, schemes, and build settings.
 - Prefer Xcode-aware tooling or `xcodebuild` over ad hoc filesystem assumptions when project structure or target membership is involved.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Use the standard top-level Xcode app repository layout: `Sources/`, `Tests/`, `Shared/`, `Extensions/`, `Configurations/`, `Scripts/`, and `Packages/`.
 - `Sources/` owns the main app target implementation and app-owned resources/support files. `Tests/` owns all test targets. `Shared/` owns reusable source intended to be compiled into the app and extension targets. `Extensions/` owns extension target roots, one folder per extension. `Configurations/` owns `.xcconfig` layers. `Scripts/` owns project-local automation and build helper scripts. `Packages/` owns local Swift packages only when a real package boundary is justified.
 - Keep those top-level roots stable; do not invent parallel names such as `AppSources`, `TestSources`, `Config`, `BuildScripts`, or `LocalPackages` for ordinary Xcode app repos.

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/core-animation-layer-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/coreaudio-modernization-repair-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/coremedia-timing-samplebuffer-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/devicecheck-app-attest-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/sf-symbols-workflow/references/snippets/apple-xcode-project-core.md

@@ -59,6 +59,8 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 ## SwiftUI and State Architecture
 
 - Treat SwiftUI views as component UI: keep them small, composable, reusable, and easy to scan from top to bottom.
+- Require one SwiftUI `View` component per file, named for that component, with that component's Xcode SwiftUI preview in the same file.
+- Do not group multiple SwiftUI view components into one Swift file, even when the views are small, private, related, nested, or currently used only by one parent.
 - Prefer straight, top-down data flow with small focused controller classes that own matching state for a view or small view cluster.
 - Do not build monolithic views, monolithic controllers, or broad shared mutable state when a smaller component boundary would be clearer.
 - Keep updates to view-driving state minimal and localized.

plugins/apple-dev-skills/skills/structure-swift-sources/SKILL.md

@@ -70,7 +70,8 @@ Use this skill as the top-level workflow for structural cleanup inside existing
 6. Apply repo-shape rules:
    - for Swift packages, prefer directories grouped by layer and feature, such as `API/<Feature>/<Concern>.swift` and `Features/<Feature>/<Concern>.swift`
    - for Xcode app projects, ensure important app-facing source directories such as `Views/`, `Controllers/`, and `Models/`
-   - for SwiftUI views, keep view files in `Views/` and pair them with `<Name>+Model.swift` and `<Name>+Modifier.swift` files when those concerns exist
+   - for SwiftUI views, keep view files in `Views/`, require exactly one SwiftUI `View` component per file, and keep that component's Xcode SwiftUI preview in the same file
+   - when splitting grouped SwiftUI views, create one `<Name>.swift` file per view component and pair it with `<Name>+Model.swift` and `<Name>+Modifier.swift` files when those concerns exist
 7. Finish with `format-swift-sources` again so the moved or split files end in a normalized state.
 
 ## Inputs