Customize View

Overview

Use this skill after the structure of a view is already correct. It adds polish and usability — styling, layout control, drill-down navigation, and external links — without rebuilding which elements belong in the view.

If the task requires changing includes, parent context, neighbors, or creating a new view, hand off to design-view first.

When to Use

• Applying colors, shapes, or opacity to elements in a view (use shared-spec palette only)
• Adjusting layout only when helpful: keep autoLayout direction optional, and add only a few rank hints for obvious anchors when needed
• Adding navigateTo links to enable drill-down navigation between views
• Attaching external documentation links to a view

Do not use for base view structure (includes/excludes, parent context, neighbors) — use design-view first.

Scope Boundary

Rule of thumb: customize the existing view; do not redesign it.

Quick Reference

Core Principles

1. Prefer Shared Spec Over Custom Styling

Before customizing colors, shapes, or styles:

1. Check shared spec first - Use specs from shared/spec-*.c4 files
2. Use defined colors - Refer to spec-global.c4 color definitions
3. Avoid custom colors - Don't create new hex colors for styling
4. Avoid custom shapes - Use kinds from shared spec, not custom shape definitions
5. If needed, ask & contribute - If styling really needs something new:

- Ask user permission first - Suggest adding it to shared spec - Contribute to spec instead of one-off customization - This keeps styling consistent across all projects

Why: Shared specs ensure consistency, maintainability, and avoid proliferation of custom styles.

2. Respect Parent Context

When customizing views, always preserve the parent/surrounding element context:

• Never hide parent container/system/zone boundaries
• Never exclude the outer context when styling inner elements
• Use styling to emphasize, not to isolate elements from their context
• Apply opacity changes carefully to avoid losing context

3. Prefer AutoLayout Before Rank

Start with autoLayout alone.

• autoLayout direction is itself optional; do not force LeftRight unless the user asked for it or the preview clearly benefits from left-to-right reading.
• Add rank only if the preview is still hard to read after the structure is already correct.
• Favor one obvious anchor at a time, such as an initiating user as rank source.
• Avoid piling up rank source, rank sink, and rank same across many elements; over-constraining the layout often produces brittle or broken views.
• If a view seems to need several rank directives to become readable, revisit the structure with design-view instead of forcing the layout here.

View Organization (Mandatory)

Hard rule: Every view MUST be nested inside a category folder using the views 'FolderName' syntax, except the index view.

Index exception: The index view must live at the root:

views {
  view index extends c1_context { }
}

Do not place any other views in the root views { } block.

Avoid duplicate prefixes: If a view is inside a category folder (e.g., views 'C1'), do not prefix the view title with the same category (e.g., avoid title 'C1 / System Context'). Use either folder name OR title prefix, not both.

Allowed categories (must use these exact folder names):

• C1 (System Context)
• C2 (Containers)
• C3 (Components)
• Use Cases (Dynamic/sequence views)
• Deployment (Infrastructure views)
• Operations (Security/monitoring/DR/CI/CD)

views 'Deployment' {
  deployment view prod_overview { ... }
}

views 'Operations' {
  deployment view security { ... }
}

See the design-view skill for full organization patterns and parent context requirements.

Visual Styling

IMPORTANT: Use colors and shapes from shared spec (shared/spec-*.c4), not custom definitions.

Available Colors (From Shared Spec)

Use only colors defined in shared/spec-global.c4:

• primary - Primary brand color
• secondary - Secondary color
• success - Success/positive state
• warning - Warning state
• danger - Error/danger state
• muted - Muted/inactive
• (Check spec-global.c4 for complete list)

DO NOT: Create new hex color definitions. If you need a color not in the spec:

1. Check spec-global.c4 first
2. If missing, ask permission and contribute to shared spec
3. Then use the spec color

Available Shapes (From Element Kinds)

Shapes come from element kinds defined in spec-*.c4 files:

• Each kind has a predefined shape (box, cylinder, etc.)
• Use the kind's shape, don't override with custom shapes

DO NOT: Define custom shapes. If a shape is needed:

1. Check if a kind exists with that shape
2. If not, contribute new kind to shared spec
3. Then use that kind

View-Level Style Overrides (Shared Spec Only)

view myView {
  include cloud.backend with {
    title 'Backend Services'
    color primary              // From shared spec
    shape database             // From kind definition
    icon tech:java
  }
}

Style Predicates (Shared Spec Colors Only)

view apiView {
  include *
  
  style * { color muted; opacity 10% }           // spec-global color
  style api.*, gateway.* { color primary; opacity 100% }  // spec-global color
  style element.tag = #deprecated { color muted }         // spec-global color
  style element.tag != #production { color secondary }    // spec-global color
}

Global Style Groups

global {
  styleGroup theme_production {
    style * { color primary }
    style element.tag = #external { color muted }
  }
}

views {
  global style theme_production
  
  view myView {
    include *
  }
}

Style Properties: Elements: color, shape, icon, opacity, border, size, textSize, multiple Colors: primary, secondary, muted, amber, gray, green, indigo, red Shapes: rectangle, storage, cylinder, browser, mobile, person, queue, bucket, document Icons: tech:, aws:, gcp:, azure:

Layout Control

Treat rank as a scalpel, not wallpaper: autoLayout first, a tiny number of hints only when the preview clearly needs them.

Auto-Layout Direction

view layered {
  include *
  autoLayout TopBottom  // Example only; omit or change direction if the user prefers otherwise
}

Do not recommend autoLayout LeftRight by default. Use it mainly when the user explicitly wants left-to-right reading or when a pipeline-like flow is clearly easier to read that way.

Rank Hints

view requestFlow {
  include *

  autoLayout TopBottom

  // Optional: keep the most obvious entry point stable
  include client with { rank source }
}

• Prefer a single obvious hint such as rank source for a user, browser, or other initiating element.
• Add rank sink only when an endpoint keeps drifting into a confusing position after autoLayout is already correct.
• Use rank same sparingly; it easily over-constrains the view and only works for siblings.
• If you feel tempted to add several rank directives, simplify the view or hand off structural changes to design-view.

Directed Includes

view dataFlow {
  include frontend, backend, database
  include frontend -> backend ->  // Direction hints
  include -> database
  
  // Optional: choose a direction only if it improves readability
  autoLayout TopBottom
}

Common Layout Patterns

Layered (TopBottom):

view layered {
  include *
  autoLayout TopBottom
}

Request Flow (Direction optional):

view flow {
  include *
  // Optional only if the initiating actor keeps drifting
  include client with { rank source }
}

Load Balanced:

view balanced {
  include *
  autoLayout TopBottom
}

Layout Troubleshooting

• Overlapping elements: First simplify includes or change autoLayout; add one targeted rank only if the preview is still unclear
• Wrong flow direction: Use directed includes or change autoLayout before reaching for more rank hints
• Elements spread out: Avoid reflexively adding rank same; reduce noise first, then add one local hint only if sibling alignment is genuinely needed

Navigation

Rule: When creating a new view, add a navigateTo link in the parent overview view so users can drill down from the higher level.

When the user asks for a customization block only, keep existing navigateTo targets stable instead of inventing a new view structure.

View-to-View Navigation

view systemOverview {
  include *
  
  include cloud.backend with {
    navigateTo backendDetails
  }
}

view backendDetails of cloud.backend {
  include *
}

Navigation Patterns

Drill-down: Context → Container → Component (navigateTo on parent elements)

view contextView {
  include *
  include cloud with { navigateTo cloudContainers }
}

view cloudContainers of cloud {
  include *
  include cloud.backend with { navigateTo backendComponents }
}

Hub-spoke: Central index with links to specialized views

Index views should extend c1context (or c0landscape if a landscape view exists) and always include braces.

view index extends c1_context {}

External Documentation Links

view epic12 {
  title "System Changes - Epic 12"
  
  description """
    Implementation details.
    See linked resources.
  """
  
  link https://my.jira/epic/12 'Epic-12'
  link https://docs.internal/spec 'Specification'
  
  include *
}

Combined Customization Example

view containers_overview {
  include *

  style * { color muted; opacity 20% }
  style api, gateway { color primary; opacity 100% }

  include user with { rank source }

  include webApp with {
    navigateTo webApp_details
  }

  link https://docs.example.internal/spec 'System specification'
}

What this example does not do:

• it does not change which elements belong in the view
• it does not invent a new detail view
• it does not rebuild the whole view structure from scratch

View Metadata

view myView {
  title "Clear, Descriptive Title"
  
  description """
    This view shows:
    - **Component A**: Handles requests
    - **Component B**: Processes data
    
    See [deployment guide](https://docs.internal/deploy).
  """
  
  #production, #deployment
  
  include *
}

Validation

• Style predicates use element.tag = #name syntax
• If an autoLayout direction is specified, it matches the user's reading preference or an obvious flow
• Any rank hints are sparse, justified, and easy to remove if the layout engine improves
• If a source/sink hint exists, it matches an obvious entry/exit point
• No conflicting rank hints (can't be both source and sink)
• Navigation targets reference valid view IDs
• External links use HTTPS with descriptive text
• View titles unique and descriptive

MCP: Use open-view to preview layout and navigation interactively

Context7: Query /likec4/likec4 for syntax validation if uncertain

Common Mistakes

❌ Custom hex colors — never define new colors inline; use only palette names from spec-global.c4 (primary, muted, danger, etc.)

❌ Custom shape definitions — shapes come from element kinds; do not override with custom shape values

❌ Rebuilding the whole view inside a customization answer — keep the existing structure and adjust only styling, layout, navigation, or links

❌ Hiding parent context with styling — never exclude or fully opacity-hide the parent container/system boundary

❌ Duplicate title prefix — if a view is inside views 'C1', don't prefix the title with "C1 /"; use folder name OR title prefix, not both

❌ navigateTo target doesn't exist — always verify the target view ID exists before adding a navigateTo link

❌ Letting customization drift into structure design — if the right answer requires changing included elements or making a new view, say so and hand off to design-view

❌ Over-constraining the layout with rank hints — start with autoLayout, then add at most a few obvious anchors; stacking rank same/rank source/rank sink often breaks views

❌ Conflicting rank hints — an element cannot be both rank source and rank sink; also, rank same only works for siblings

Output

Polished views with appropriate styling, logical layout, and clear navigation paths.