Design, refine or review application interfaces, adaptive layouts, components, themes and accessibility. Integrates Material 3, Apple HIG and the iOS/iPadOS 27 UI Kit with bundled Figma canvas, screen and component workflows. Use for UI mockups, design systems and requested implementation; preserve the product's chosen framework. Application icon artwork uses the separate icon-design package.
Instructions
---
name: ui-design
description: Design, refine or review application interfaces, adaptive layouts, components, themes and accessibility. Integrates Material 3, Apple HIG and the iOS/iPadOS 27 UI Kit with bundled Figma canvas, screen and component workflows. Use for UI mockups, design systems and requested implementation; preserve the product's chosen framework. Application icon artwork uses the separate icon-design package.
metadata:
version: "1.0.8"
---
# UI Design
Deliver usable, editable interfaces with deliberate hierarchy, layout, typography, color and interaction. This is one integrated skill: its Apple guidance and Figma workflows are included as references, so installing separate Apple or Figma skills is not required to obtain these instructions. Connected tools and licensed assets remain separate capabilities.
For substantive design, briefly remind the user about Figma and follow [Figma access and fallback](references/design-access.md): prefer connected Figma tools, then an authorized Chrome Figma session, then complete the design locally if neither is available. Respect code-only and no-computer-control instructions; missing Figma access must not stall ordinary work.
## Select the product's design system
Start with the requested task, existing product and target platform. Preserve its framework, functions, navigation requirements and localization. An illustration or app icon reference does not select a new interface system.
- **PiscesOS:** the user explicitly selected the [Apple iOS 27 community design system](references/apple-ios27-community.md) for interfaces and icons. Use its verified components with current Apple HIG as the primary visual direction. Retain [Material design](references/material-design.md) as a supplementary layout, interaction, adaptation and accessibility reference. Support computer, tablet and phone, preserving native Windows behavior and the existing runtime. Read [PiscesOS UI context](references/piscesos-ui.md).
- **Apple-native UI or an explicitly requested Apple mockup:** use Apple HIG and the actual iOS/iPadOS 27 UI Kit components. Read [Apple UI workflow](references/apple-ui-workflow.md) and the current resource links below.
- **Another established product:** reuse its design system, component library and tokens. Apply relevant platform and accessibility guidance without imposing Material or Apple styling.
For a new product whose system is unspecified, infer a suitable direction from the brief and reference. Ask only when a missing requirement changes the design. Treat reference screenshots as evidence about visible hierarchy and style, not verified component internals.
## Design the requested experience
For an app or tool that should resemble PiscesOS, read [PiscesOS app family](references/piscesos-app-style.md). Inherit the visual family while designing for the app's own tasks; shell launcher layouts are not universal app layouts. The portable `piscesos-app-design` package carries accepted assets and example evidence for another Codex.
When the task actually modifies the PiscesOS Desktop shell, read [Desktop shell and Settings behavior](references/piscesos-desktop-shell.md). Preserve Figma proportions, the reserved Start layout, Taskbar-only controls/auto-hide and stable Settings scrolling; do not apply shell-specific rules to unrelated app layouts.
Identify the primary task, information hierarchy, navigation, important states and the requested screen or component inventory. Distinguish a single view, a component family and a complete design system; a small change does not require rebuilding the whole library.
Choose the layout structure before tuning decoration. Adapt navigation and panes to available space; retain the same functions across supported devices. Include relevant loading, empty, error, disabled, focus, selected and success states. Long text, large text, keyboard entry and narrow windows must remain usable.
Make the main task and important controls understandable at first glance. Simplify competing containers, accents and decorative layers before adding polish. Creative freedom in color and finish remains within the chosen design system, product identity and accepted references; it does not authorize an unrelated palette or arbitrary material treatment. Read [Visual direction and restraint](references/visual-direction.md) when choosing or revising the style.
For PiscesOS, apply the latest [iPhone clarity and material calibration](references/iphone-restraint.md): quiet content surfaces, deliberate text/action hierarchy and selective subtle navigation/control glass. Do not translate app-icon depth into beveled buttons, stacked translucent cards or heavy shadows across the interface. Preserve functional host behavior and use Material 3 as a supplementary reference.
Use a coherent type hierarchy and semantic color roles with correct foreground/background pairings. Light and dark UI themes are coordinated token modes, not an inversion of a screenshot. Materials should clarify hierarchy and keep controls readable; glass is optional and platform-dependent. Use actual available fonts and coherent interface symbols with accessible control names.
For Apple-directed UI, including PiscesOS, inspect the selected design system and actual UI Kit styles, modes and component variants. Read current Color and Materials guidance before choosing fills or effects. Resolve palette, typography, shape and material through that visual family; use Material references for useful functional guidance without importing a competing visual system. A crafted app icon's bevel or shadow does not prescribe the treatment of all interface panels. When merely previewing an icon on light/dark UI surfaces, reuse its exact complete artwork; do not recolor the icon as though a background comparison were a theme variant.
The user's current PiscesOS app artwork uses rounded protective glass shells with glass material on the primary foreground content as well. Read [Display layered glass app artwork](references/glass-shell-artwork.md) when placing or previewing those icons. Preserve the supplied shell, foreground transmission, local edge response, proportions and clean upload bounds; let Icon Design author both material levels. The separate explicit UI request selects Apple-directed interfaces; it still does not turn every content surface into glass.
Select only the Apple reference relevant to the task:
| Decision | Included reference |
| --- | --- |
| Hierarchy and platform behavior | [Principles](references/apple/principles.md), [Platforms](references/apple/platforms.md) |
| Layout and navigation | [Layout](references/apple/layout.md), [Components](references/apple/components.md), [Patterns and input](references/apple/patterns-gestures.md) |
| Text, color and materials | [Typography and symbols](references/apple/typography-symbols.md), [Materials and color](references/apple/materials-color.md) |
| Accessibility | [Accessibility](references/apple/accessibility.md) |
These community summaries provide orientation. Verify version-specific controls, dimensions and other exact specifications against the current official pages or actual kit; label an inference as an inference.
## Use the actual kit and design file
[Apple Design Resources](https://developer.apple.com/design/resources/) is the official version index. The [iOS and iPadOS 27 UI Kit](https://www.figma.com/community/file/1651309003795292092/ios-and-ipados-27) supplies native interface components. Read [Figma Assets workflow](references/figma-assets.md) to inspect connected libraries, variants, styles and modes before creating lookalike controls.
For the user's selected community system, read [the inspected page map and application workflow](references/apple-ios27-community.md). It records actual color, text, material and platform-component evidence and its extraction limits. Keep community provenance separate from official resource authorship; verify exact values from actual components rather than guessing from screenshots.
Reuse compatible components and tokens before creating replacements. Retain existing user content and editable hierarchy. A screenshot of the entire interface is a review reference; it is not a substitute for editable text, components and layout.
## Bundled Figma workflows
All required local guidance is inside this package:
| Operation | Read before the operation |
| --- | --- |
| Every `use_figma` call | [Canvas/API workflow](references/figma/figma-use/workflow.md), then its relevant API references |
| Build or update a composed screen | [Screen workflow](references/figma/figma-generate-design/workflow.md), plus Canvas |
| Tokens, components, variants or a design system | [Component workflow](references/figma/figma-generate-library/workflow.md), plus Canvas |
| A requested custom shader effect/fill | [Shader workflow](references/figma/figma-shaders/workflow.md), before `create_shader` or `update_shader` |
The bundled files contain Figma's published workflow guidance with local routing adaptations; they are not hidden instructions from Figma's on-canvas agent. Follow the enabled tool's current schema and any skill prerequisite in the environment. Original Figma `skillNames` labels in these modules are usage logging, not extra package installations. Read [Sources and integration](references/sources.md) for provenance and the bundled-module map.
Use the [access sequence](references/design-access.md) before falling back from unavailable cloud tools. A local editable prototype can serve a code-only or local-output brief directly. Report the actual result and keep independent authorized work moving. A local file is not a completed Figma import.
## Review and deliver
Inspect hierarchy, alignment, text wrapping, contrast, state coverage, input behavior and adaptation at relevant window sizes. Verify requested components and themes structurally, then review the rendered result. Fix demonstrated discrepancies; stop when the requested scope passes.
Before delivering or uploading a standalone transparent PNG that should fit its visible artwork, remove unwanted nearly transparent exterior halos in source and fit the visible silhouette to the explicitly requested pixel dimensions. A nonzero-alpha bounding box alone can preserve invisible margins. Render clean tight vector bounds at the required output size; do not silently deliver a smaller crop or add the margin back. Keep rounded corners, proper antialiasing, holes and internal shadows, and preserve aspect ratio. Read [Raster bounds and upload fit](references/raster-export.md) and use [trim_transparent_png.py](scripts/trim_transparent_png.py) with a suitable visible-alpha threshold when needed; reopen the output and inspect dimensions, visible bounds and actual UI-slot fit. Put layout spacing and optional surrounding UI shadows in layout rules, rather than hidden image margins. Preserve intentional outer shadows or full canvases for screenshots, aligned layers, sprites and required host contracts as separate clearly named outputs.
Deliver the editable source or affected Figma nodes, a useful preview and requested exports or implementation. State what was actually applied and any material untested interaction. Use English for new deliverables unless requested otherwise; preserve existing localization. App identity artwork belongs to the separate Icon Design package.
