Merge branch 'improvement/introduction-vision-pages' into q/1.0

Author: bert-e

stories/AgenticSurfaces.mdx

@@ -0,0 +1,40 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="UI and agentic surfaces" />
+
+<style>{`
+  .sbdocs-content h2 { margin-top: 5rem; }
+  .sbdocs-content h3 { margin-top: 3rem; }
+`}</style>
+
+# UI and agentic surfaces
+
+This reflects the state of the industry in Q2 2026, as agentic tools are entering the mainstream.
+
+## The new interaction landscape
+
+UI has traditionally been the primary surface between users and software. That is changing: the graphical interface is no longer the only point of contact. It is one representation of the system's state and capabilities.
+
+### New surfaces
+
+Natural language, conversational agents, voice-to-text, and agentic workflows are becoming legitimate interaction surfaces for any system. Sometimes alongside graphical interfaces, sometimes replacing them.
+
+### Designing for autonomous systems
+
+Designing for autonomous systems means designing their behavior, their limits, and the degree of supervision the user retains over them. Components must account for the expression of intent rather than explicit navigation. 
+
+### The role of UI
+
+The UI remains valuable precisely because it represents the mental model of the systems it exposes. That representation must be accurate, legible, and trustworthy. The UI library is one tool in a broader interaction stack.
+
+## Designed for humans and tools
+
+Core UI is currently designed for humans. Extending that to tools is the direction we are building toward.
+
+### Documented intent
+
+Every component, every rule, and every constraint exists for a reason, and that reason is documented. As AI-assisted development becomes standard, a design system that communicates intent only to human readers leaves half its audience behind. Where possible, these rules are enforced through tooling like a linter.
+
+### A shared body of knowledge
+
+The design principles in this Storybook, the component guidelines, the component code, and the composition patterns, from primitives to screens, together form a body of knowledge: not just how to use the library, but why it was built the way it was. That knowledge should be accessible to an AI tool generating a new component, to a developer evaluating a design decision, and to a designer questioning a pattern.

stories/Introduction.mdx

@@ -2,31 +2,69 @@ import { Meta } from '@storybook/addon-docs/blocks';
 
 <Meta title="Introduction" />
 
-# Get started
+<style>{`
+  .sbdocs-content h2 { margin-top: 5rem; }
+  .sbdocs-content h3 { margin-top: 3rem; }
+`}</style>
 
-Core UI, Scality Design System, is a reusable component library that helps Scality contributors build UIs faster. The goal is to make building durable UIs more productive and satisfying.
+# Core UI
 
-## Install
+Core UI is a reusable component library designed to help teams (including Scality) build consistent UIs faster. The source is available on [GitHub](https://github.com/scality/core-ui).
 
-SDS components are written in React, and its stories are written in [Component Story Format](https://medium.com/storybookjs/component-story-format-66f4c32366df).
 
-## Objective
 
-A Design System is an ecosystem of guidelines, tools, components, which support teams ship more efficiently consistent design.
+## Design Principles
 
-- Synchronising designers, product teams, and developers
-- Building a shared vocabulary for reducing communication issues
-- Having one solution for one component
-- Easier testing at component level
-- Faster iterations with established design patterns
+These principles share a common conviction: when a user makes a mistake, it's the interface that failed. A well-designed UI does not rely on the user being right.
 
-Examples of public design systems:
+### Feedback
 
-- Material Design - by Google
-- Carbon D- by IBM
-- Lighting - by Salesforce
-- Polaris - by Shopify
-- Atlassian Design - by Atlassian
-- Fluent - by Microsoft
-- AirBnb Design - by AirBnb
-- Human Interface - by Apple
+For clarity's sake, every action should produce a visible response (not for emotional effect). The user should never wonder whether something happened, succeeded or failed. 
+
+This applies to different levels, such as clicks, form submissions, background operations, and destructive actions alike.
+
+### Affordance
+
+Every element must clearly signal whether it is interactive, clickable or static. There is no room for ambiguity.
+
+### Findability
+
+In complex systems, the measure of good information architecture is not the number of clicks but how easily a user can locate what they need. Structure, labeling, and hierarchy should make navigation feel obvious. Good UX goes unnoticed.
+
+### Trust and transparency
+
+Interfaces must be trustworthy and explainable. The user should always be able to understand what happened, why it happened, and what will happen next. 
+
+The user should always be able to supervise, override, or understand the system's intent.
+
+### Observability
+
+The interface is a mirror of the system it represents. Status, health, ongoing actions, and failure states should be surfaced clearly and consistently. A user who cannot see the state of the system cannot trust it. If the system's state is opaque, the interface is incomplete.
+
+### Simplicity
+
+Complex tasks should be achievable through interfaces that feel simple. This is not about reducing features, it is about offering the right level of abstraction. The interface should absorb complexity so the user does not have to.
+
+### Predictability
+
+Rely on recognized patterns and proven conventions. Consistent use across contexts builds user confidence. Deviate only when the use case genuinely requires it.
+
+### Consistency
+
+Use the same component for the same pattern. The same problem or action should not be solved by different solutions. It creates confusion for users who learn one interaction and encounter a different one elsewhere.
+Consistency applies both visually (how things look) and behaviorally (how they respond to interaction).
+
+### Accessibility
+
+#### Contrast
+
+The color of an interactive or readable element and its background should have a contrast ratio significant enough. There is a value for it: at least 4.5:1. 
+This can be checked with the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) or with Chrome DevTools.
+
+#### Color usage
+
+Color should not be the only way of conveying information or indicating an action. Color perception varies across screens, contexts, cultures, and individual conditions.
+
+#### Keyboard navigation
+
+All content and fields should be accessible through keyboard controls. Focus must always be visible, and tab order must follow the visual flow of the page.