docs: layout guide

CHANGELOG.md

@@ -20,7 +20,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### BREAKING CHANGES
 - Use regular components instead of `Label` in `RadioGroupItem` @layershifter ([#1070](https://github.com/stardust-ui/react/pull/1070))
 - Remove `Flex.Gap` component, and convert the `gap` styles to `margins` on the child elements of the `Flex` component @mnajdova ([#1074](https://github.com/stardust-ui/react/pull/1074))
-- Dropdown: control highlightedIndex from Dropdown @silviuavram ([#966](https://github.com/stardust-ui/react/pull/966))
+- `Dropdown`: control highlightedIndex from `Dropdown` @silviuavram ([#966](https://github.com/stardust-ui/react/pull/966))
 
 ### Fixes
 - Add aria posinset and setsize, hide menu indicator from narration @jurokapsiar ([#1066](https://github.com/stardust-ui/react/pull/1066))
@@ -36,6 +36,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add `placeholderColor` variable for `Input` component in Teams theme @layershifter ([#1092](https://github.com/stardust-ui/react/pull/1092))
 - Add and export files icons in Teams theme @codepretty ([#1094](https://github.com/stardust-ui/react/pull/1094))
 
+### Documentation
+- Add layout guide @kuzhelov ([#1091](https://github.com/stardust-ui/react/pull/1091))
+
 <!--------------------------------[ v0.23.1 ]------------------------------- -->
 ## [v0.23.1](https://github.com/stardust-ui/react/tree/v0.23.1) (2019-03-13)
 [Compare changes](https://github.com/stardust-ui/react/compare/v0.23.0...v0.23.1)

docs/src/components/GuidesNavigationFooter.tsx

@@ -0,0 +1,45 @@
+import * as React from 'react'
+import { Link } from 'react-router-dom'
+import { Button, Flex, Divider } from '@stardust-ui/react'
+
+type PageDescriptor = {
+  name: string
+  url: string
+}
+
+type GuidesNavigationFooterProps = {
+  previous?: PageDescriptor
+  next?: PageDescriptor
+}
+
+const GuidesNavigationFooter: React.FC<GuidesNavigationFooterProps> = ({ previous, next }) => (
+  <>
+    <br />
+    <Divider size={1} />
+    <br />
+    <Flex gap="gap.small">
+      {previous && (
+        <Button
+          as={Link}
+          content={previous.name}
+          icon="arrow left"
+          iconPosition="before"
+          primary
+          to={previous.url}
+        />
+      )}
+      {next && (
+        <Button
+          as={Link}
+          content={next.name}
+          icon="arrow right"
+          iconPosition="after"
+          primary
+          to={next.url}
+        />
+      )}
+    </Flex>
+  </>
+)
+
+export default GuidesNavigationFooter

docs/src/components/Sidebar/Sidebar.tsx

@@ -316,6 +316,13 @@ class Sidebar extends React.Component<any, any> {
         to: '/theming-examples',
         styles: menuItemStyles,
       },
+      {
+        key: 'layout',
+        content: 'Layout',
+        as: NavLink,
+        to: '/layout',
+        styles: menuItemStyles,
+      },
       {
         key: 'integrate-custom',
         content: 'Integrate Custom Components',

docs/src/examples/components/Box/index.tsx

@@ -1,6 +1,6 @@
-import { Alert } from '@stardust-ui/react'
 import * as React from 'react'
 import { Link } from 'react-router-dom'
+import { Alert } from '@stardust-ui/react'
 
 import Types from './Types'
 
@@ -10,18 +10,26 @@ const HeaderExamples = () => (
       <p>
         <code>Box</code> component should be used carefully, in almost all cases you don't need it.
       </p>
+      <ul>
+        <li>
+          For layouts and positioning refer to <Link to="/components/flex">Flex</Link> and{' '}
+          <Link to="/components/grid">Grid</Link> components (and general{' '}
+          <Link to="/layout">Layout guide</Link>).
+        </li>
+        <li>
+          Consider to use <Link to="/components/text">Text</Link> component to wrap text.
+        </li>
+        <li>In other cases consider to style existing components via theming features.</li>
+        <li>
+          You also can{' '}
+          <Link to="/integrate-custom-components">create your own custom component</Link> for custom
+          behaviors.
+        </li>
+      </ul>
       <p>
-        For layouts and positioning please prefer <Link to="/components/flex">Flex</Link> and{' '}
-        <Link to="/components/grid">Grid</Link> components, we also have{' '}
-        <Link to="/components/text">Text</Link> component to wrap text. In other cases please try to
-        use existing components and apply styles via theming features. You also can{' '}
-        <Link to="/integrate-custom-components">create your own custom component</Link> for custom
-        behaviors.
-      </p>
-      <p>
-        Remember that <code>styles</code> that applied directly to any component are not friendly
-        for theme switching, prefer to use <code>variables</code> instead of <code>styles</code> for
-        overrides.
+        Remember that <code>styles</code> prop applied directly to an element most probably will
+        break theme switching scenarios - thus, prefer to use <code>variables</code> instead of{' '}
+        <code>styles</code> for overrides.
       </p>
     </Alert>
 

docs/src/examples/components/Flex/index.tsx

@@ -1,10 +1,19 @@
 import * as React from 'react'
+import { Alert } from '@stardust-ui/react'
+import { Link } from 'react-router-dom'
 
 import Rtl from './Rtl'
 import Types from './Types'
 
 const FlexExamples = () => (
   <>
+    <Alert styles={{ display: 'block' }}>
+      <p>
+        Get more information on Stardust's approach to layout from{' '}
+        <Link to="/layout">Layout guide</Link>.
+      </p>
+    </Alert>
+
     <Types />
     <Rtl />
   </>

docs/src/examples/components/Grid/index.tsx

@@ -1,11 +1,20 @@
 import * as React from 'react'
+import { Alert } from '@stardust-ui/react'
+import { Link } from 'react-router-dom'
 
 import Rtl from './Rtl'
 import Types from './Types'
 import Variations from './Variations'
 
 const GridExamples = () => (
   <>
+    <Alert styles={{ display: 'block' }}>
+      <p>
+        Get more information on Stardust's approach to layout from{' '}
+        <Link to="/layout">Layout guide</Link>.
+      </p>
+    </Alert>
+
     <Types />
     <Variations />
     <Rtl />

docs/src/examples/components/Segment/index.tsx

@@ -1,11 +1,22 @@
 import * as React from 'react'
+import { Alert } from '@stardust-ui/react'
+import { Link } from 'react-router-dom'
 
 import Rtl from './Rtl'
 import Types from './Types'
 import Variations from './Variations'
 
 const SegmentExamples = () => (
   <>
+    <Alert styles={{ display: 'block' }} warning>
+      <p>
+        <code>Segment</code> component shouldn't be used to handle layout aspects. To address
+        layouts and positioning aspects refer to <Link to="/components/flex">Flex</Link> and{' '}
+        <Link to="/components/grid">Grid</Link> components (and general{' '}
+        <Link to="/layout">Layout guide</Link>).
+      </p>
+    </Alert>
+
     <Types />
     <Variations />
     <Rtl />

docs/src/routes.tsx

@@ -13,6 +13,7 @@ import PageNotFound from './views/PageNotFound'
 import QuickStart from './views/QuickStart'
 import Theming from './views/Theming'
 import ThemingExamples from './views/ThemingExamples'
+import LayoutGuide from './views/Layout'
 import IntegrateCustomComponents from './views/IntegrateCustomComponents'
 
 const Router = () => (
@@ -95,6 +96,7 @@ const Router = () => (
         <DocsLayout exact path="/accessibility" component={Accessibility} />
         <DocsLayout exact path="/theming" component={Theming} />
         <DocsLayout exact path="/theming-examples" component={ThemingExamples} />
+        <DocsLayout exact path="/layout" component={LayoutGuide} />
         <DocsLayout exact path="/shorthand-props" component={ShorthandProps} />
         <DocsLayout
           exact

docs/src/views/Accessibility.tsx

@@ -1,9 +1,9 @@
 import * as React from 'react'
-import { NavLink } from 'react-router-dom'
 import DocPage from '../components/DocPage/DocPage'
 import CodeSnippet from '../components/CodeSnippet'
+import GuidesNavigationFooter from '../components/GuidesNavigationFooter'
 
-import { Header, Divider, Segment, Button } from '@stardust-ui/react'
+import { Header, Segment } from '@stardust-ui/react'
 
 const code = (content: string): React.ReactNode => <code>{content}</code>
 
@@ -522,23 +522,9 @@ export default () => (
       'https://github.com/stardust-ui/accessibility/blob/master/CONTRIBUTING.md',
     )}
 
-    <Divider />
-    <br />
-    <Button
-      as={NavLink}
-      content="Quick Start"
-      icon="arrow left"
-      iconPosition="before"
-      primary
-      to="quick-start"
-    />
-    <Button
-      as={NavLink}
-      content="Theming"
-      icon="arrow right"
-      iconPosition="after"
-      primary
-      to="theming"
+    <GuidesNavigationFooter
+      previous={{ name: 'Quick Start', url: 'quick-start' }}
+      next={{ name: 'Theming', url: 'theming' }}
     />
   </DocPage>
 )

docs/src/views/IntegrateCustomComponents.tsx

@@ -1,8 +1,6 @@
 import * as React from 'react'
 import { NavLink } from 'react-router-dom'
 import {
-  Button,
-  Divider,
   Header,
   Provider,
   createComponent,
@@ -13,6 +11,7 @@ import {
 import DocPage from '../components/DocPage/DocPage'
 import ExampleSnippet from '../components/ExampleSnippet/ExampleSnippet'
 import { ReactChildren } from 'src/types'
+import GuidesNavigationFooter from '../components/GuidesNavigationFooter'
 
 interface StyledButtonProps {
   className?: string
@@ -276,16 +275,6 @@ export default () => (
       <NavLink to="accessibility">Accessibility guide</NavLink> section.
     </p>
 
-    <br />
-    <Divider size={1} />
-    <br />
-    <Button
-      as={NavLink}
-      content="Theming Examples"
-      icon="arrow left"
-      iconPosition="before"
-      primary
-      to="/theming-examples"
-    />
+    <GuidesNavigationFooter previous={{ name: 'Layout', url: 'layout' }} />
   </DocPage>
 )