Copying old content from https://github.com/anandrajeswaran/apple-ux-guide to this repo. That old repo will be deleted (and recreated as a personal fork) so that this one is the truth.

Layout.md

@@ -0,0 +1,5 @@
+# Layout
+
+## Compose Hierarchies with NSStackViews/UIStackViews
+
+## Use Layout Anchor Constraints

README.md

@@ -1,5 +1,8 @@
+# Apple UX Guide
 
-# Contributing
+This guide contains best practices for building great experiences and writing sustainable code using Apple's UX Frameworks. Guidance here comes from a combination of our collective practical experiences and documentation from Apple and other 3rd parties. This is meant to be a living document and all contents are perpetually open for debate and improvement.
+
+## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
@@ -13,7 +16,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
 
-# Legal Notices
+## Legal Notices
 
 Microsoft and any contributors grant you a license to the Microsoft documentation and other content
 in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode),

StoryboardsAndXibs.md

@@ -0,0 +1,16 @@
+# Storyboards
+
+## Convention
+In most cases on both macOS and iOS, it is recommended to avoid storyboards (and XIBs) in favor of programmatically creating views and view controllers
+
+## Rationale
+- Runtime performance analysis has shown us that disk operations degrade poorly for users with slower devices. Since creating UI programmatically allows us to avoid reading the storyboard/nib from disk at runtime, we should do so.
+- Storyboard XML is becoming simpler over time, but still falls short of human readability. This makes code reviews difficult and merge conflicts likely. The generated XML is easily bloated and it's difficult to be sure everything we're adding is necessary and intentional.
+- Keeping view hierarchy construction in storyboards can leave code simpler, but there are some best practices that can keep code simple while avoiding the pitfalls above:
+    - [Compose view hierarchies With NSStackViews/UIStackViews](Layout.md#Compose-Hierarchies-with-NSStackViews/UIStackViews).
+    - [Use layout anchor constraints](Layout.md#Use-Layout-Anchor-Constraints)
+    - [Create the view hierarchy in loadView](ViewControllers.md#Construct-View-Hierarchies-in-loadView)
+
+## Exceptions
+- Launch Screens on iOS are required to be specified as storyboards.
+- The main menu bar for a macOS app is required to be specified in a XIB.

ViewControllers.md

@@ -0,0 +1,3 @@
+# View Controllers
+
+## Construct View Hierarchies in loadView