corp-v1-channel-ui-ux-3darch/SKILL.md

---
name: corp-v1-channel-ui-ux--3darch
description: "Use when operating or synchronizing a Corp v1 project's UI/UX channel. Maintains project frontend design work, Penpot artifacts, design-system decisions, accessibility evidence, and implementation handoffs while correlating verified activity across the project's seven channels."
version: 1.3.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [corp-v1, discord, channel, ui-ux, frontend-design, penpot, accessibility]
    related_skills: [corp-v1--main, home-v1-discord, documentation-docusaurus, corp-v1--glossary]
---

# Corp v1 UI/UX Channel

## 3D Architecture Wizzard Project Adoption

This is the primary project-adopted skill for **3D Architecture Wizzard** (`3darch`).

- Central source: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-ui-ux
- Source branch: `test`
- Source commit: `de8c40cf43e08a63ca0be38a4b4404fbe2427885`
- Adopted repository: https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/corp-v1-channel-ui-ux--3darch
- Application: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch
- Documentation: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch-documentation
- Environment namespace: `CORP_V1_3DARCH_*`
- Global diagram skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio
- Global glossary skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--glossary
- Project automation: none; no scheduler job is authorized.

Project engineering peers:
- `development-branching-strategy--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-branching-strategy--3darch
- `development-gitops-argo-cd--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-gitops-argo-cd--3darch
- `development-monorepo-pnpm--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-monorepo-pnpm--3darch
- `development-scripts--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-scripts--3darch
- `devsecops-ci-cd-gitea--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/devsecops-ci-cd-gitea--3darch
- `documentation-docusaurus--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/documentation-docusaurus--3darch
- `template-engine-copier--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/template-engine-copier--3darch

Mapped Discord channel: `corp-v1-3darch-ui-ux` (`1543925251191349260`).


## Overview

This central reference skill owns frontend experience and interface design work for a Corp v1 project's `ui-ux` channel. The channel sits immediately after `architecture` in the project channel order:

```text
general → scope → architecture → ui-ux → kanban → delivery → releases
```

Penpot is the current design platform. Penpot files are the editable design source; Discord is the discussion and evidence surface, and the project documentation repository stores durable design records, links, decisions, statuses, and implementation handoff evidence.

This skill does not own product scope, system architecture, task admission, frontend implementation, release approval, or deployment. Route those decisions to their mapped channels. Corp v1 scheduler prohibition applies: this channel uses human- or event-triggered coordination and must not create, attach, retain, or operate cronjobs or scheduler jobs.

Load the project's adopted `documentation-docusaurus--<code>` skill before changing project documentation. Load global `corp-v1--glossary` when defining reusable terminology. Use the project's development and delivery skills when design work reaches implementation.

## Shared Corp v1 System Login

When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1--main` and use only the Bitwarden-injected runtime secrets named:

```text
HL_V1_SSO_EMAIL
HL_V1_SSO_PASSWORD
```

Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.

## When to Use

Use this skill when:

- operating in `corp-v1-<code>-ui-ux`;
- creating or reviewing frontend user journeys, information architecture, wireframes, mockups, and prototypes;
- maintaining Penpot projects, files, pages, components, libraries, tokens, and interaction flows;
- defining responsive behavior, empty/loading/error/success states, and accessibility expectations;
- documenting UI/UX decisions and preparing a frontend implementation handoff;
- reconciling design drift reported by Scope, Architecture, Delivery, Releases, or user feedback.

Do not use this skill for backend design, infrastructure, C4 architecture, frontend coding, task admission, release decisions, or generic visual brainstorming unrelated to an approved project outcome.

## Approved Information Boundary

Inspect only the seven channels belonging to the same project:

```text
corp-v1-<code>-general
corp-v1-<code>-scope
corp-v1-<code>-architecture
corp-v1-<code>-ui-ux
corp-v1-<code>-kanban
corp-v1-<code>-delivery
corp-v1-<code>-releases
```

Never inspect or correlate another project's channels. Resolve exact channel IDs from the current guild before cross-channel work; cached IDs are hints, not durable identity.

## Authority and Approval Gates

UI/UX may autonomously:

- analyze verified user needs and approved Feature outcomes;
- create clearly marked exploratory or proposed design artifacts;
- maintain design inventories, traceability, accessibility checks, and handoff structure;
- identify contradictions, missing states, and frontend design risks;
- correct non-semantic documentation defects.

A human project team member must explicitly approve a design package before it is treated as implementation-ready unless a preserved project-local authorization override delegates that exact decision. Approval must identify the Feature or design package, approver, evidence message or record, date, and resulting status. Silence, a Penpot link, an agent statement, a merged documentation PR, or green CI is not design approval.

Project-local authorization overrides marked by `CORP_V1_PROJECT_AUTHORIZATION_OVERRIDE` supersede conflicting generic actor restrictions but never remove exact-item decisions, durable evidence, accessibility review, validation, credential safety, or platform controls.

## Input Contract

Before producing implementation-ready frontend design, verify:

1. stable Epic/Feature identity and authoritative Scope link;
2. approved problem, intended user outcome, acceptance outcomes, and relevant user/persona evidence;
3. Architecture constraints, interfaces, data availability, security/privacy boundaries, and affected containers/components;
4. target platforms, viewport classes, supported input methods, localization needs, and accessibility constraints;
5. current frontend implementation or design-system baseline when one exists.

Proposed work may be explored before all inputs are final, but it must remain visibly `Exploratory` or `Proposed` and must not be handed to Delivery as ready.

## Penpot Design Source

Penpot is the editable source of truth for interface design at this time.

### Hermes Penpot MCP

Hermes uses **only** `penpot-zcube-v1` for Penpot automation. The official plugin-based `penpot` MCP is not part of the operating model and must not be configured, requested, or treated as a fallback. Treat the server's configured `enabled` state and per-tool include list as an operational safety boundary:

```yaml
mcp_servers:
  penpot-zcube-v1:
    enabled: true
    # Local stdio, browserless Penpot RPC operations.
    tools:
      include: [explicitly approved tools only]
```

- **`penpot-zcube-v1`** provides authenticated team/project/file discovery and approved page, frame, shape, text, component, alignment, media, snapshot, and library-read operations. It runs as a local stdio child of Hermes and uses the Bitwarden-managed Penpot API credential. It must remain pinned, production-audited, restricted to the approved Penpot instance, and fail-closed through `tools.include`.
- The pinned build does not expose native rendered PNG/SVG export, plugin-runtime tokens, variants, interactions, live selection, or Penpot frontend visual inspection. Report those exact capability limits honestly; do not reintroduce the official MCP to obtain them. Review aids may use a separately approved non-MCP rendering path, while Penpot remains the editable source.

Set `mcp_servers.penpot-zcube-v1.enabled` to `true` or `false` through supported Hermes configuration, then start a fresh agent session or restart the gateway for the change to take effect. Use `hermes mcp configure penpot-zcube-v1` to toggle individual tools. Disabling the server never authorizes an alternate Penpot MCP. Keep sampling disabled.

Before browserless mutation through `penpot-zcube-v1`:

1. verify the exact team, project, file, and page IDs;
2. inspect the current file revision and target objects;
3. create and lock a snapshot when the change is material and the tool is enabled;
4. apply one coherent change batch within the project boundary;
5. read back object identity, parentage, geometry, style/content, and resulting revision;
6. stop on revision conflict or ambiguous duplicate names rather than retrying blindly;
7. use the backend API or a separately approved cleanup path for destructive file/project/team operations, which remain disabled in the community MCP allowlist.

If work requires a capability absent from `penpot-zcube-v1`, report the specific limitation and continue with supported editable work. Do not ask for plugin attachment or configure the official Penpot MCP.

For every governed design package:

- use a project-owned Penpot project/file rather than a personal or unrelated workspace;
- record the verified Penpot project and file URL without embedding credentials or private tokens;
- use stable, descriptive page, board, flow, component, and state names;
- preserve editable components and libraries instead of flattening the design into screenshots;
- define desktop, tablet, and mobile behavior where the Feature requires them;
- include keyboard, focus, contrast, semantics, reduced-motion, and error-recovery expectations;
- represent loading, empty, error, permission-denied, offline, and success states where applicable;
- record material design decisions and review status in project documentation;
- use exports only as review aids—never as a replacement for the editable Penpot source.

If Penpot requires login and the active session is not authenticated, first follow the shared Corp v1 SSO policy above using the injected runtime secrets against the verified Penpot origin. If injection is unavailable or authentication is rejected, stop and report only the non-sensitive credential-injection or access blocker. Never guess credentials or move design work into an unapproved substitute platform.

## Design Package Contract

A reviewable design package contains, when applicable:

```text
Feature ID and title
Status: Exploratory | Proposed | Approved | Superseded | Rejected
Penpot project/file/page links
User journey and primary task flow
Information architecture and navigation
Wireframes or low-fidelity flow
High-fidelity responsive screens
Reusable components, variants, and design tokens
Interaction and transition behavior
Loading/empty/error/success/permission states
Accessibility requirements and review evidence
Content and validation rules
Architecture/interface assumptions
Open questions, risks, and alternatives
Approver and approval evidence
Implementation handoff link and target tasks
```

Do not mark a design package `Approved` without authoritative evidence. Preserve superseded versions and decisions through links rather than silently replacing history.

## Design System and Frontend Contract

### Penpot shared-library component-root invariant

On Penpot 2.17.1, every published component's `mainInstanceId` must resolve to a `frame` or `group`. Never publish a component directly from a primitive `rect`, `circle`, `text`, image, or path: the Libraries dashboard component renderer handles only `frame` and `group` roots and otherwise crashes deterministically, for example with `No matching clause: rect`.

Build a container root first, move the component background, labels, and other visual children inside it, and create the component from that container. Before sharing or reporting a design-system library as healthy, read back every active component definition, resolve each main instance in the page object map, assert its root type is `frame` or `group`, and open the authenticated team Libraries route to confirm that no `No matching clause` page error occurs.

When repairing a malformed library, first prove whether product files contain instances of the affected component IDs. Replace invalid definitions with valid container-root definitions in one exact-revision batch; preserve visual children and parentage; then distinguish active records from Penpot recovery records marked `deleted: true`. Purge only the retired malformed records after active-count, root-type, child-count, library-link, and authenticated-dashboard readback pass. Do not treat a raw component-map count as the active count, and do not claim success merely because the file or library link exists.

Prefer project-level reusable components and tokens over one-off screens. Record at least:

- typography, spacing, color, elevation, iconography, and interaction tokens;
- component anatomy, variants, states, behavior, and content limits;
- responsive rules and breakpoints;
- accessibility semantics, focus order, keyboard behavior, and contrast targets;
- mapping from Penpot components to intended frontend component names when known;
- intentional deviations from the project design system.

Corp v1 interfaces use sharp rectangular geometry by default (`border-radius: 0`); do not introduce pills, rounded cards, or rounded inputs unless the project team explicitly approves the exception.

UI/UX specifies observable frontend behavior and design intent. Delivery chooses and validates implementation details within approved Architecture and engineering constraints. If implementation reveals a design contradiction, return it to `ui-ux` with exact evidence rather than silently changing the intended experience.

## Handoffs

### Scope → UI/UX

Scope provides the stable Feature, user problem, value, acceptance outcomes, evidence, and approval state. UI/UX does not rewrite the product outcome or invent approval.

### Architecture → UI/UX

Architecture provides system boundaries, interfaces, data, security/privacy constraints, platform limits, and affected components. UI/UX raises conflicts rather than drawing an experience that the approved architecture cannot support.

### UI/UX → Kanban and Delivery

After design approval, provide:

- stable Feature/design package identity;
- exact Penpot links and approved revision evidence;
- responsive screens and interaction flows;
- component, state, content, and accessibility acceptance criteria;
- mapped implementation tasks and dependencies;
- unresolved risks or explicit `none`;
- approval evidence.

UI/UX does not self-admit tasks to Kanban Focus and does not implement frontend code. Kanban owns task admission and flow; Delivery owns implementation and review.

### Delivery and Releases → UI/UX

Delivery reports feasibility issues and implementation deviations with screenshots, routes, commits, or test evidence. Releases reports production feedback and regressions. UI/UX updates the design package or records an approved exception while preserving history.

## Documentation Contract

Maintain durable UI/UX records in the project documentation repository. Do not create a new top-level documentation menu solely because this channel exists unless Corp v1 governance or the project team separately approves the information-architecture change.

Link each design package from its authoritative Feature record and relevant Architecture overview. Documentation must identify the Penpot source, status, approval evidence, affected frontend surface, accessibility expectations, and implementation tasks. Reusable terms belong in the final top-level Glossary and are linked rather than duplicated.

## Verification Workflow

1. Resolve the exact project code and seven same-project channel IDs.
2. Read enough channel and repository evidence to establish current Scope, Architecture, design, Delivery, and release state without duplicating prior work.
3. Verify the Penpot file belongs to the intended project and the referenced pages/boards exist; use only `penpot-zcube-v1` for Penpot MCP work.
4. Review the complete user flow, responsive states, component variants, content rules, and accessibility expectations.
5. Confirm proposed versus approved status and immutable approval evidence.
6. Update durable project documentation using the adopted Docusaurus skill.
7. Validate documentation structure, links, typecheck, production build, and deployed readback when documentation changes.
8. Read back the exact remote artifact and any posted Discord guidance.
9. Verify that no Corp project cronjob or scheduler job exists.
10. Verify `penpot-zcube-v1` is the only configured Penpot MCP, its `enabled` state and selected tools are correct, the API credential is present without disclosure, and exact readback passed.
11. Report exact Penpot links, documentation paths, commit/PR/CI evidence, approval status, remaining gates, and any inaccessible Penpot surface.

## Common Pitfalls

1. Treating a screenshot or exported image as the editable design source.
2. Marking a design approved because it exists in Penpot.
3. Designing without verified Scope outcomes or Architecture constraints.
4. Omitting loading, empty, error, permission, responsive, or keyboard states.
5. Using personal Penpot files without project ownership or durable links.
6. Letting Delivery silently diverge from the approved design.
7. Turning UI/UX into a frontend implementation channel.
8. Creating a new documentation menu without separate information-architecture approval.
9. Inspecting another project's channels.
10. Creating or retaining a cronjob or scheduler job for this channel.
11. Exposing Penpot credentials, session data, private tokens, or authorization headers.
12. Reintroducing or requesting the official plugin-based `penpot` MCP instead of operating solely through `penpot-zcube-v1`.
13. Enabling all community-server tools, especially destructive team/project/file administration, instead of maintaining a fail-closed include list.
14. Retrying a low-level `update-file` mutation after an uncertain response without revision and object readback.
15. Publishing a component whose main instance is a primitive shape. Penpot 2.17.1 requires a `frame` or `group` root for Libraries dashboard rendering.

## Verification Checklist

- [ ] Only the seven same-project channels were inspected.
- [ ] Stable Feature and Architecture inputs are linked.
- [ ] Penpot project/file/pages are verified and editable.
- [ ] Design status and approval evidence are explicit.
- [ ] Responsive, interaction, component, content, and state behavior is covered.
- [ ] Accessibility expectations and review evidence are recorded.
- [ ] Project design-system reuse and approved deviations are visible.
- [ ] Implementation handoff links exact tasks, dependencies, and acceptance evidence.
- [ ] Project documentation and remote/deployed artifacts were verified when changed.
- [ ] No Corp project cronjob or scheduler job exists.
- [ ] `penpot-zcube-v1` was the only configured Penpot MCP and was restricted to approved tools.
- [ ] Mutations include exact file/page/object/revision readback; unsupported capabilities are reported without adding another Penpot MCP.
- [ ] Every active shared-library component resolves to a `frame` or `group` root, deleted recovery records are excluded from active counts, and the authenticated Libraries route opens without a `No matching clause` error.