# PortaShape Use Cases and End-to-End Workflows

## The value of unified workflows

A PortaShape use case should cross capabilities without feeling like a handoff between tools. The same selected values, controls, mappings, policies, and provenance follow the user from discovery through execution.

## 1. Runtime component tuning

**Goal:** Tune a production-connected component and preserve the result.

1. Connect the repository, token system, and development runtime.
2. Discover component properties, CSS variables, design tokens, events, and animation parameters.
3. Generate a component inspector and live preview.
4. Adjust spacing, color, typography, timing, easing, or feature flags.
5. Compare variants and capture a successful preset.
6. Validate accessibility, brand, performance, and allowed ranges.
7. Promote the preset into a source patch or configuration artifact.
8. Save the surface, preset, and provenance as `.posh` artifacts.

The same work can later become a reusable control for designers or an organization-wide component policy.

## 2. Website migration and reconstruction

**Goal:** Transfer a website value for value wherever meaningful equivalents exist.

1. Connect source and destination websites.
2. Discover content, schemas, routes, assets, styles, tokens, components, settings, options, permissions, interactions, and runtime behavior.
3. Generate source and destination explorers using the same vocabulary.
4. Accept or create mappings for equivalent elements.
5. Translate formats such as colors, units, paths, enums, content references, and dates.
6. Transmute structures where direct equivalents do not exist.
7. Preview destination rendering and behavior.
8. Expose unsupported, lossy, or unresolved values.
9. Run validation for routes, content completeness, accessibility, brand, behavior, permissions, and assets.
10. Execute in stages with approvals and rollback points.
11. Save mapping, run report, decisions, and destination snapshot.

The result is not only the migrated website. It is a portable, auditable explanation of the migration.

## 3. Design-system translation

**Goal:** Convert one token and component language into another.

1. Connect both token systems and component libraries.
2. Classify semantic roles rather than relying only on token names.
3. Surface colors, typography, spacing, radii, shadows, motion, and variants.
4. Map direct equivalents.
5. Generate or transform scales where structures differ.
6. Preview representative components using destination tokens.
7. validate contrast, consistency, allowed values, and unmapped roles.
8. Save a layered base mapping plus organization and product overrides.

## 4. Internal tool generation

**Goal:** Create an operational interface from an API or schema.

1. Connect an API, database, and permission model.
2. Discover records, fields, actions, relationships, constraints, and workflows.
3. Ask PortaShape to create a tool for a task such as customer support or content operations.
4. Review generated tables, forms, filters, actions, and status views.
5. Bind local presentation state and authoritative server operations using explicit ownership contracts.
6. Add role-specific options and system-wide settings.
7. Save the surface and workflow as a reusable project library.

## 5. Configuration snapshot, comparison, and promotion

**Goal:** Understand environment drift and safely promote selected changes.

1. Capture development, staging, and production snapshots.
2. Compare settings, options, feature flags, tokens, integrations, content configuration, and runtime deviations.
3. Classify intended differences versus drift.
4. Select changes to promote.
5. Preview destination impact and policy checks.
6. Require approval for high-risk settings.
7. execute a controlled promotion.
8. Record the run and create a new baseline snapshot.

## 6. Brand governance

**Goal:** Make brand guidance operational.

1. Connect brand documentation, token systems, components, content samples, and runtime pages.
2. Convert brand rules into semantic elements, constraints, examples, controls, and validators.
3. Generate a brand inspector for pages, components, motion, and content.
4. Detect deviations and show affected source elements.
5. Tune candidate corrections in preview.
6. Promote accepted fixes and store the policy library.

## 7. Content-system migration

**Goal:** Move content while preserving structure, relationships, routes, states, and editorial intent.

1. Discover content types, fields, references, assets, locales, states, routes, and permissions.
2. Map schemas and editorial concepts.
3. Translate dates, identifiers, rich text, paths, and status values.
4. Transmute incompatible block structures or generate missing destination fields.
5. Validate references, assets, routes, publishing state, and completeness.
6. Run incrementally and rerun changed items.
7. Retain per-item provenance and unresolved decisions.

## 8. Motion system laboratory

**Goal:** Tune and standardize animation across a product.

1. Connect the motion library and live components.
2. Expose duration, easing, spring, interpolation, trigger, and sequencing values.
3. Generate synchronized controls, curves, timelines, and previews.
4. Compare variations and record runtime performance.
5. Identify parameters repeatedly adjusted together.
6. Promote them into semantic motion presets and constraints.
7. Translate presets into another animation framework when needed.

## 9. AI and agent control surface

**Goal:** Make an AI system inspectable and governable.

1. Connect prompts, tools, routing, context sources, memory policies, evaluations, and runtime traces.
2. Model durable configuration separately from session options and live execution state.
3. Generate controls for safe parameters and read-only views for sensitive or authoritative data.
4. Compare runs and inspect provenance from input through tool calls to output.
5. Map configurations between model providers or agent runtimes.
6. Validate policy, privacy, cost, latency, and evaluation thresholds.
7. Save approved configurations and workflow definitions.

## 10. Web-native PortaShape surface development

**Goal:** Build a generated or hand-composed PortaShape interface using the included runtime library.

1. Declare state authority, submitted values, URL state, and DOM writers.
2. Use server-rendered HTML for authoritative projections.
3. Use htmx for narrow requests, swaps, history, and related multi-region updates.
4. Use Alpine.js for local focus, visibility, selection, and disposable previews.
5. Use semantic events as documented contracts.
6. Use native controls and progressive enhancement.
7. Test lifecycle, cleanup, races, errors, security, accessibility, and direct routes.
8. Package the resulting surface patterns and component contracts into a PortaShape library.

## 11. Customer onboarding and personalization portability

**Goal:** Import a customer’s data, organization settings, and user options into a product.

1. Connect the customer source and product destination.
2. Separate organization settings from individual user options.
3. Map records, roles, preferences, and content.
4. Validate permissions and scope boundaries.
5. Preview the customer-specific destination surface.
6. Execute with a run report and reusable customer-type mapping.

## 12. Operational pattern discovery

**Goal:** Turn repeated manual work into reusable capability.

1. Observe which values, filters, actions, and mappings are repeatedly used together.
2. Suggest a higher-level control, saved view, workflow, alert, or transform.
3. Show the supporting evidence and generated rule.
4. Let users accept, edit, reject, or scope the abstraction.
5. Save accepted patterns into a project or organization library.

## Common workflow invariant

Every use case follows the same PortaShape promise:

```text
real system → shared model → usable surface → deliberate relation or change
            → preview and validation → controlled execution → portable evidence
```