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

name, description, version, author, license, metadata

name	description	version	author	license	metadata
corp-v1-channel-ui-ux	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.	1.2.0	Hermes Agent	MIT	hermes tags related_skills corp-v1 discord channel ui-ux frontend-design penpot accessibility corp-v1--main home-v1-discord documentation-docusaurus corp-v1--glossary

Corp v1 UI/UX Channel

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:

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.

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:

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:

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, stop at the login wall and request user authentication. Never guess credentials or move design work into an unapproved substitute platform.

Design Package Contract

A reviewable design package contains, when applicable:

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

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.

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.