Implement custom docs template

.storybook/custom-docs/blocks/Import.tsx

@@ -0,0 +1,35 @@
+import {Source, useOf} from '@storybook/addon-docs/blocks';
+
+interface DocsParameters {
+  importSubpath?: string;
+  exportName?: string;
+}
+
+interface PreparedMeta {
+  parameters?: {docs?: DocsParameters};
+}
+
+export const Import = () => {
+  const {preparedMeta} = useOf('meta', ['meta']) as {preparedMeta: PreparedMeta};
+  const exportName = preparedMeta.parameters?.docs?.exportName;
+  const importSubpath = preparedMeta.parameters?.docs?.importSubpath;
+
+  if (!exportName || !importSubpath) {
+    return null;
+  }
+
+  const builtPath = `import ${exportName} from '@jetbrains/ring-ui-built/${importSubpath}';`;
+  const sourcePath = `import ${exportName} from '@jetbrains/ring-ui/${importSubpath}';`;
+
+  return (
+    <>
+      <h3>{'Import'}</h3>
+
+      <p>{'Quick start (ready-to-use ES modules):'}</p>
+      <Source language='tsx' code={builtPath} />
+
+      <p>{'Build from sources (webpack):'}</p>
+      <Source language='tsx' code={sourcePath} />
+    </>
+  );
+};

.storybook/custom-docs/custom-docs.tsx

@@ -0,0 +1,12 @@
+import {Controls, Primary, Title} from '@storybook/addon-docs/blocks';
+
+import {Import} from './blocks/Import';
+
+export const CustomDocs = () => (
+  <>
+    <Title />
+    <Primary />
+    <Import />
+    <Controls />
+  </>
+);

.storybook/main.js

@@ -1,5 +1,5 @@
 import {createRequire} from 'node:module';
-import {dirname, join} from 'node:path';
+import {dirname, join, resolve} from 'node:path';
 
 const require = createRequire(import.meta.url);
 const path = require('path');
@@ -12,7 +12,8 @@ export default {
   stories: [
     // Make welcome stories default
     '../src/welcome.stories.tsx',
-    '../src/**/*.stories.{js,ts,tsx}',
+    '../src/**/!(template)*.mdx',
+    '../src/**/!(template)*.stories.{js,ts,tsx}',
   ],
 
   features: {
@@ -24,9 +25,17 @@ export default {
   webpackFinal(config) {
     ringConfig.componentsPath.push(__dirname, path.resolve(__dirname, '../src'));
 
+    const autoDocumentationRule = config.module.rules.find(rule => /react-docgen-loader\.js$/.test(rule.loader));
+    const mdxRule = config.module.rules.find(
+      rule =>
+        rule.test.toString().startsWith('/\\.mdx') && rule.use?.some(u => u.loader?.includes('@storybook/addon-docs')),
+    );
+
     config.module.rules = [
       ...ringConfig.config.module.rules,
       config.module.rules.find(rule => /react-docgen-loader\.js$/.test(rule.loader)),
+      autoDocumentationRule,
+      mdxRule,
       {
         test: /\.md$/,
         loader: 'raw-loader',
@@ -44,6 +53,14 @@ export default {
       {test: /\.m?js$/, resolve: {fullySpecified: false}},
     ];
 
+    config.resolve = {
+      ...config.resolve,
+      alias: {
+        ...config.resolve?.alias,
+        '@custom-docs': resolve(__dirname, './custom-docs'),
+      },
+    };
+
     const serverUri = pkgConfig.hub;
     const clientId = pkgConfig.clientId;
     const hubConfig = JSON.stringify({serverUri, clientId});

.storybook/preview.ts → .storybook/preview.tsx

@@ -10,6 +10,7 @@ import strictModeDecorator from './strict-mode-decorator';
 import stylesDecorator from './styles-decorator';
 import themeDecorator from './theme-decorator';
 import {darkMatcher, theme} from './theme';
+import {CustomDocs} from './custom-docs/custom-docs';
 
 const updateTheme = () => applyTheme(darkMatcher.matches ? Theme.DARK : Theme.LIGHT, document.documentElement);
 updateTheme();
@@ -28,6 +29,7 @@ export const parameters = {
       notes ?? component?.__docgenInfo?.description,
     theme,
     codePanel: true,
+    page: CustomDocs,
   },
   a11y: {
     test: 'error',

.storybook/template/template.mdx

@@ -0,0 +1,23 @@
+{/* Base MDX template for component documentation */}
+
+import { Meta, Title, Primary, Controls } from '@storybook/addon-docs/blocks';
+import { Import } from '@custom-docs/blocks/Import';
+
+import * as TemplateStories from './template.stories';
+
+<Meta of={TemplateStories} />
+
+{/* Component name */}
+<Title />
+
+{/* Component description (optional for now) */}
+<p>Write your component description here.</p>
+
+{/* Main example */}
+<Primary />
+
+{/* Import section */}
+<Import />
+
+{/* Props table */}
+<Controls />

.storybook/template/template.stories.tsx

@@ -0,0 +1,46 @@
+// This is a template Storybook configuration.
+
+import {type Meta, type StoryObj} from '@storybook/react-webpack5';
+
+// Replace with your component import
+import Button, {type ButtonProps} from '../../src/button/button';
+
+// Example Storybook metadata
+const meta: Meta<typeof Button> = {
+  title: 'Entity/Template', // example: Components/Button
+  component: Button,
+
+  parameters: {
+    // Docs parameters for the custom Import block
+    docs: {
+      importSubpath: 'components/template/template', // update to match your folder structure
+      exportName: 'Template', // name of the exported component
+    },
+  },
+
+  // Prop controls and descriptions for the Docs panel
+  argTypes: {
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the button when true',
+    },
+    onClick: {
+      action: 'clicked',
+      description: 'Callback fired when the button is clicked',
+    },
+  },
+
+  // Default args for the basic story
+  args: {
+    children: 'Click me',
+    disabled: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+// Add your stories here
+export const Basic: Story = {
+  render: (args: ButtonProps) => <Button {...args} />,
+};

CONTRIBUTING.md

@@ -80,3 +80,15 @@ so every component could be inspected via running storybook (`npm start`) and th
 - Click "Generate" and then "Copy"
 - Paste the copied text into `/design-tokens.json`
 - Run `npm run update-styles`
+
+### Creating a new Story
+
+1. Copy the base story template: [template.stories.tsx](.storybook/template/template.stories.tsx)
+
+2. Rename it to your component (e.g. `button.stories.tsx`) and adjust imports and metadata.
+
+Storybook will automatically generate docs with an example, import section, and props table.  
+If you need a custom documentation layout (extra sections, guidelines, etc.),  
+use [template.mdx](.storybook/template/template.mdx) as a starting point.
+
+

src/progress-bar/progress-bar.stories.tsx

@@ -24,6 +24,12 @@ const meta: Meta<typeof ProgressBar> = {
       );
     },
   ],
+  parameters: {
+    docs: {
+      importSubpath: 'components/progress-bar/progress-bar',
+      exportName: 'ProgressBar',
+    },
+  },
   argTypes: {
     value: {
       control: {type: 'range', min: 0, max: 1, step: 0.1},

test-helpers/jest-globals.js

@@ -47,7 +47,7 @@ Object.defineProperty(window, 'matchMedia', {
   }),
 });
 
-setProjectAnnotations(require('../.storybook/preview.ts'));
+setProjectAnnotations(require('../.storybook/preview.tsx'));
 
 HTMLDialogElement.prototype.show = jest.fn();
 HTMLDialogElement.prototype.showModal = jest.fn();