React components library for Telefonica Design System (Mística)

Getting started

Install

yarn add @telefonica/mistica

or

npm install @telefonica/mistica

Start using @telefonica/mistica

Before using any of our components you have to add <ThemeContextProvider> in the root of your React app. Here is a complete example of a form with two text fields and a submit button:

import {createRoot} from 'react-dom/client';
// Import Mistica styles. Depending on the bundler you use, you may need to import it in a different way.
import '@telefonica/mistica/css/mistica.css';

// Use mistica components
import {
  ThemeContextProvider,
  Form,
  Box,
  Stack,
  TextField,
  EmailField,
  ButtonLayout,
  ButtonPrimary,
  alert,
  getMovistarSkin,
} from '@telefonica/mistica';

const App = () => (
  <Form
    onSubmit={(formData) =>
      alert({
        title: 'This is your data',
        message: JSON.stringify(formData, null, 2),
      })
    }
  >
    <Box padding={16}>
      <Stack space={16}>
        <TextField name="name" label="Name" />
        <EmailField name="email" label="Email" />
        <ButtonLayout primaryButton={<ButtonPrimary submit>Send</ButtonPrimary>} />
      </Stack>
    </Box>
  </Form>
);

const misticaTheme = {
  skin: getMovistarSkin(),
  i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
};

const container = document.getElementById('app');
const root = createRoot(container);
root.render(
  <ThemeContextProvider theme={misticaTheme}>
    <App />
  </ThemeContextProvider>
);

The theme prop in ThemeContextProvider is mandatory, and you can use it to configure some aspects of the library. There are multiple settings but the only two mandatory fields are skin and i18n. Read the theme config doc for more info.

⚠️ Usually, the theme object is constant and won't need to change dynamically in your application, in that case we recommend to extract it to an external const variable outside of the component, this way the object reference will be the same in every re-render. If for some reason the theme must be dynamic in your app, consider to memoize it (for example, with React.useMemo hook).

Mística in Next.js app router

If you are using Next.js app router, we highly recommend enabling the following experimental config:

experimental: {
  optimizePackageImports: ['@telefonica/mistica'];
}

This will improve the tree shaking of the library, reduce the bundle size and the build time. For more info read this Next blog post: https://vercel.com/blog/how-we-optimized-package-imports-in-next-js

Components

Explore the components in Mistica storybook

Start prototyping interfaces with Mistica components in the Mística playroom

AI / LLM Integration

Mistica ships documentation optimised for AI coding assistants. The package includes a doc/llms.md file with concise component references, critical rules, and links to detailed documentation — all inside node_modules.

Using the skill

If you use any agent that supports skills, you can install the bundled Mistica skill so the agent automatically reads the right documentation before generating UI code:

npx skills add telefonica/mistica-web

Once installed, your agent should load the skill whenever you ask it to build Mistica UIs and will consult the documentation automatically.

For LLMs reading this file

If you are an AI assistant and node_modules/@telefonica/mistica is available in the project:

1. Read node_modules/@telefonica/mistica/doc/llms.md — start here, it has critical rules and an overview.
2. Read the specific doc files referenced inside llms.md based on the task at hand.

If node_modules/@telefonica/mistica is not available, fall back to the GitHub repository:

• Main LLM reference: https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md
• Components: https://github.com/Telefonica/mistica-web/blob/master/doc/components.md
• Layout: https://github.com/Telefonica/mistica-web/blob/master/doc/layout.md
• Patterns: https://github.com/Telefonica/mistica-web/blob/master/doc/patterns.md

More docs

• Examples
• Understanding Mistica's layout components
• Working with forms
• Theme config options
• Customize default texts
• Analytics
• Fonts
• Testing notes
• Using Lottie
• Mística CSS

Development

• yarn test: run tests
• yarn test-acceptance: run acceptance tests headless (you need to start storybook first)
• yarn test-acceptance --ui: run acceptance tests with ui (you need to start storybook first)
• yarn lint: check codestyle
• yarn ts-check: check static types (run yarn build first — the type check requires generated declaration files in dist/)
• yarn build: build package
• yarn storybook: starts storybook
• yarn playroom: starts playroom

More about Mística

• Mística, the Telefonica Design System

Mística in other platforms

• Android
• iOS

Contributing

See CONTRIBUTING.md

Mística Community

About Mística Community

If you are building a Mística Community component, place it inside the src/community folder and don't forget to export it in the src/community/index.ts file to make it public.